WI4 Troubleshooters Guide

1

Web Interface 4.0 Troubleshooter’s Guide

Author Jay Tomlin Department Technical Support

Revision 2.0 Distribution Public


2

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

3

6.4 Troubleshooting ASP.NET Errors.................................................................... 68 6.4.1 Try a Simple ASPX File .......................................................................... 68 6.4.2 IIS ASP.NET Registration........................................................................ 69

7. Reference Materials ...................................................................................... 71 7.1 Features not available on Web Interface for UNIX .............................................. 71 7.2 XML Service Dependencies .......................................................................... 72 7.3 IMA Error Codes Relayed by the XML Service..................................................... 73

7.3.1 Error Handling in Presentation Server 4.0 and beyond .................................... 73 7.4 HTTP Server Environment Variables ............................................................... 79 7.5 Debug.aspx............................................................................................. 82

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


4

1. What’s new in Web Interface 4.0 1.1 New features for the end user

Multilingual User Interface – A single Web Interface site supports users in five languages simultaneously: English, German, French, Spanish, and Japanese. Web Interface detects the user’s locale and displays the appropriate language automatically.

Java Client Fallback – If a Win32 client logs into Web Interface without having a Win32 ICA client installed, the ICA Client for Java can be automatically delivered.

Bandwidth control – Users may indicate their current bandwidth during logon in order to enable or disable features that affect ICA session bandwidth.

Increased UI control – Users may be allowed to control aspects of the Web Interface display: which language to use, how many columns of application icons to display, and whether to use full or compact UI layout.

Session Reliability through Secure Gateway – This is technically a feature of the 9.0 ICA Client and Secure Gateway 3.0, but session reliability through Secure Gateway also requires Web Interface 4.0 and is enabled or disabled via an option in the Web Interface Access Suite Console extension.

1.2 New features for the administrator Access Suite Console management – An extension for the Access Suite Console

has been developed that allows GUI administration of both Windows and JSP site variants. One instance of the Access Suite Console can be used to manage multiple remote Web Interface servers. The new Access Suite Console plugin replaces WIAdmin and PNAgentAdmin.

Remote Configuration – As an alternative to storing the configuration in a local WebInterface.conf file, administrators may now choose to store the site configuration in the Presentation Server 4.0 IMA database. When configured this way, Web Interface downloads its configuration from the XML Service upon startup and after any change is made in the Access Suite Console.

Site groups – Administrators can group multiple Web Interface sites into a single logical unit and use the Access Suite Console to configure all sites as a group. All sites in the group share a single central configuration. When a change is made in the Access Suite Console, all sites in the load-balanced group are updated immediately.

Multi-site support – Multiple Presentation Server, Program Neighborhood Agent, or Conferencing Manager sites can co-exist on a single Web Interface server. The Access Suite Console includes easy wizard-driven tasks for creating new sites, as well as moving, repairing, or deleting sites.

Easy UI customization – Administrators can alter the appearance of Web Interface without having to edit any scripts. The Access Suite Console offers wizard-driven control over Web Interface’s overall layout, colors, logo, icon columns, welcome message text, header, and footer.

Two-factor authentication on UNIX – The JSP variant of Web Interface now supports RSA SecurID or Secure Computing SafeWord for Citrix. While the Windows version of Web Interface continues to use the native third-party DLLs to provide this feature, the JSP version uses the RADIUS authentication protocol to communicate with the RSA or SafeWord server.

Novell NDS authentication via LDAP – Web Interface 4.0 for Windows is now capable of performing Novell NDS integration without requiring the Novell client

5

on the Web server. NDS authentication is still unavailable on Web Interface for UNIX.

1.3 Installer changes The installer for the Windows version of Web Interface is now a self-extracting

executable instead of an MSI file. The installer is also multilingual; setup can be performed in English, German, French, Spanish, or Japanese. The Access Suite Console is a prerequisite for Web Interface on Windows; if the Access Suite Console is not installed, the Web Interface installer aborts.

Sites must be created manually - After installation on a new server, no Web Interface site is created by default. After installation, the administrator must run the Access Suite Console and create a new site. A default static Web page is created at /Citrix/MetaFrame/ with news to this effect: “Before you can use the Web Interface, you must create one or more sites using the MetaFrame Access Suite Console. In the console tree, right-click on Web Interface under the Configuration Tools extension, then select Create site and follow the instructions in the wizard.”

Some components of Web Interface 4.0 for Windows are placed in the Program Files\Citrix\Web Interface\4.0 folder. This is a departure from Web Interface 3.0, but these central files in no way prevent a server from hosting multiple independent Web Interface 4.0 sites.

1.4 XML Service changes The XML Service in Presentation Server 4.0 includes the following enhancements:

Built-in Secure Ticket Authority – The STA is now bundled with the Citrix XML Service. The standalone STA installer is no longer included.

Improved error handling - Where in prior versions the XML Service would always return “Unspecified error” for any unrecognized IMA failure, the XML Service now includes the IMA error code as part of its response to Web Interface. The complete list of error codes is documented below.

1.5 Design Changes New SDK - The underlying Java classes which drive Web Interface have been

completely rewritten. The new SDK is referred to as Web Interface Next Generation or WING. The WING classes were designed from the ground up to be more flexible and more powerful than previous versions of the NFuse SDK.

No more template.ica - Instead of using template.ica as the starting point for all rendered ICA files, Web Interface 4.0 generates all ICA file parameters programmatically. If a manual addition or correction needs to be made, administrators may add entries to one or more ICA override files. Any parameter defined in an ICA override file always takes precedence over its corresponding computed value. Application-specific parameters may be inserted into the override file, for example to allow just one application to run in a non-seamless window.


6

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 or without SP1

x86 IIS 6.0 .Net/J# 1.1 N/A

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

Server 8.x WebLogic WebLogic

Red Hat Enterprise Edition x86 WebSphere Application Server 5.x

WebSphere WebSphere

2.2 Supported Web Browsers Tier 1 O/S

Internet Explorer 6.0 Windows XP, Windows 2000 SP4+

Safari 1.x Mac OS X (JICA only)

Mozilla 1.x Red Hat Linux Enterprise

Tier 2 O/S

Internet Explorer 6.0 Windows 2003

Internet Explorer 5.5 Windows 2000, CE.NET 4.1 (WYSE 3125se)

Netscape 7.x Windows XP, Windows 2000

Pocket IE 2003 PocketPC 2003 (HP iPAQ H5550, Dell Axim 5)

Internet Explorer 6 CE.NET 4.2 (WYSE 3125se & HP t5510)

Tier 3 (Touch Test) O/S

Internet Explorer 5.21 MacOS X

Netscape 6.x MacOS 9

7

3. Installation and site management This section provides details about what changes are made to a server during the installation of Web Interface and how to create and manage Web Interface sites.

3.1 Types of sites Web Interface 4.0 supports multiple independent sites on a single Web server, and each site may be one of the following three types:

MetaFrame Presentation Server site – Provides access to a user’s application set in an HTML format

Program Neighborhood Agent Services site – Provides XML Services to Program Neighborhood Agent clients

MetaFrame Conferencing Manager site – Provides guest attendee access to a conference hosted by MetaFrame Conferencing Manager

Throughout this guide, the term “Web Interface site” is meant to apply to all three types of sites.

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

3.2.1 What’s installed The following directories are created beneath each MetaFrame Presentation Server site’s root:

• <site-root>/auth – Scripts and DLLs that deliver the Web Interface to end users before they have authenticated

• <site-root>/site – Scripts and DLLs that deliver the Web Interface to end users after they have authenticated

• <site-root>/conf – Configuration files, static string text files, and ICA override files

• <site-root>/bin – DLLs that provide the Web Interface Java classes and other native Windows code

• <site-root>/ICAWEB – ICA and RDP Client binaries, that override the common clients stored in Program Files\Citrix\Web Interface\4.0\ICAWEB_common

Other metabase modifications made by the site manager tool include the following:

• IIS is configured to parse .ica files using aspnet_isapi.dll


8

• Custom error pages are defined that deliver a Web Interface-branded error message instead of the default IIS error message when a problem occurs

• On Windows Server 2003, IIS is set to allow the ASP.NET Web service extension • If “Set as the default page for the IIS site” was chosen during site creation,

WebInterface.htm is added to the top of the Web site’s default document list

3.2.2 What’s not installed The following items were included in Web Interface 3.0 but are no longer present with Web Interface 4.0 sites:

• WIAdmin has been replaced by the Access Suite Console. There is no HTML-based administration tool for Web Interface 4.0.

• Default, certificate and integrated virtual directories are no longer created to achieve single sign-on or smart card authentication through IIS. Instead, all users access the login page at <site-root>/auth/login.aspx and individual file settings in the metabase are used to trigger authentication for non-explicit methods.

• PNAgent is not included as part of a new Presentation Server site; it must be created and managed separately.

• PNAgentAdmin has been replaced by the Access Suite Console.

3.2.3 Windows 2000 Domain Controllers not supported If you install Web Interface 4.0 on a Windows 2000 domain controller, some problems will arise because the ASPNET account does not exist. After installation completes, an error appears saying “Error creating trustee object while handling <Servername>\ASPNET.” The same error appears whenever you attempt to create a new site. On Windows 2000 servers that are not domain controllers, installing the .NET framework creates a local ASPNET account to run the .NET framework worker process, and the Web Interface installer expects this account to exist. On Windows 2000 Service Pack 4 domain controllers, the ASPNET account is not created by the .NET framework installation; the IWAM account is used instead. See Microsoft article 315158. Also, attempting to access any ASP.NET site will initially fail with the error message “An internal error occurred. Please contact your administrator.” As discussed in Microsoft article 824308, the following steps need to be taken in order to use ASP.NET on a Windows 2000 Service Pack 4 domain controller:

1. Edit the Domain Controller Security Policy. 2. Select Local Policies > User Rights Assignment and define a policy to allow the

“Impersonate a client after authentication” privilege to the domain IWAM account.

3. Type SECEDIT /REFRESHPOLICY MACHINE_POLICY /ENFORCE. 4. Type IISRESET.

Web Interface 4.0 should not be installed on a Windows 2000 Domain Controller.

3.3 Web Interface 4.0 Command-line installation and site management Web Interface 4.0 supports installation, uninstallation, site creation, site modification, and site removal via command-line utilities. These utilities can be used as an alternative to the Access Suite Console for some tasks or as a means to perform an unattended installation.

9

3.3.1 Web Interface 4.0 for Windows command-line installation To get started, unzip the WebInterface.exe package to a directory. If WinZip is not installed on a Windows 2003 server, you can simply rename the WebInterface.exe program to WebInterface.zip and then expand it using Windows’ built-in zip handler. The unzipped contents will include the file WebInterfaceSetup.exe:

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


10

3.3.2 WebInterfaceSetup.exe command line options

3.3.3 Site Definition Strings Wherever <sitedef> appears in the previous table, this refers to a double quoted and comma-separated list of name=value pairs which describe a Web Interface, Program Neighborhood Agent, or MetaFrame Conferencing Manager site. For example, the following <sitedef> string describes a Web Interface 4.0 site installed at the Default Web

Option Meaning Behavior if absent

-noasc Bypasses the check for the Access Suite Console for MetaFrame Presentation Server. This allows you to install Web Interface without installing the console.

Without this option, the installer will exit (with an error message in an interactive install) if the correct version of the Access Suite Console is not installed.

-p <path> Installs site management tool and language packs to <path>. This option implies a silent installation of Web Interface.

Site management tool and language packs are installed to C:\Program Files\Citrix (or equivalent).

-q Installs Web Interface silently. With none of these options, the installer GUI is displayed.

-c <sitedef> Installs a new site defined by <sitedef>, which is a comma separated list of <arg>=<value> pairs. See the next table for a specification.

No site is created.

-e <path> Installs the ICA clients from <path> which must point to an ICAWEB folder. This option can only be specified to the first time setup wrapper or the UNIX pre-install script. If absent, the ICA clients are not installed. This option can only be used if the –p option is also specified.

ICA Client files are not installed.

-g <logpath> Log the operation(s) performed and save the log files in <logpath>.

No log file is created.

-h or -? Displays the program’s version and a summary of the accepted command line options, then quits. All other command line options are ignored.

Help is not displayed.

-i Prints out a summary of all sites currently installed on the machine. This option can only be specified by itself.

No summary is shown.

-l <language> Use language <language> for the GUI rather than the default language. If this option is used along with any of the other options, it has no effect (since the GUI will not be displayed). Possible values for <language> are en, de, fr, es, and ja (English, German, French, Spanish, and Japanese respectively).

If no other command line options are supplied, the user is prompted to select a language for the installation program.

-m <sitedef> Modifies an existing site specified by <sitedef>. Existing sites are not modified.

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

-u Uninstalls the Web Interface. This option can only be specified by itself.

Web Interface is not uninstalled.

11

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>

Where <service_list> is one or more ; separated <server>:<port> pairs.

Specifies the configuration source to be either a local configuration file or the Configuration Service at the 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.


12

Option Meaning

ECS=<server>:<port> Configures an initial ECS service at host <server> and port <port>. If configuration source is not local, an error occurs. Ignored if a MetaFrame Conferencing Manager site is not being installed. If absent, defaults to localhost:9000.

ECSSecure=Yes|No Sets whether communications with the initial ECS service are secured using SSL. If configuration source is not local or if no ECS option is specified, an error occurs. If absent, defaults to No.

WIApplyChangesURL=<URL> Sends the specified URL as the Apply Changes URL when registering the Web Interface site with the Configuration Service. Ignored if not using the Configuration Service. If absent, a guessed URL is sent.

PNAApplyChangesURL=<URL> Sends the specified URL as the Apply Changes URL when registering the Program Neighborhood Agent site with the Configuration Service. Ignored if not using the Configuration Service. If absent, a guessed URL is sent.

MCMApplyChangesURL=<URL> Sends the specified URL as the Apply Changes URL when registering the MetaFrame Conferencing Manager site with the Configuration Service. Ignored if not using the Configuration Service. If absent, a guessed URL is sent.

3.3.4 Web Interface for Windows examples The following examples illustrate how to perform command-line installation or site management of Web Interface 4.0 Example 1 – Install Web Interface 4.0 for Windows and create a local site To install Web Interface and create a Web Interface site on the Default Web Site beneath /Citrix/MetaFrame, setting it to be the default destination for this Web server, using a local WebInterface.conf file for configuration:

WebInterfaceSetup.exe –c "WIDest=1:/Citrix/MetaFrame,Config=Local,XMLService=mps01:80,WIDefaultSite=Yes" Example 2 – Add a site that uses remote configuration This command adds two new sites to an existing Web Interface 4.0 server. The new sites will use the XML services MPS401:8080 and MPS402:8080 as configuration sources as well as the sources for published application information. We have created a new site in IIS that we wish to use to serve the Web Interface sites. The new IIS site has an identifier of 894881:

13

We wish to install the Web Interface and Program Neighborhood Agent Services sites on this new IIS Web site. cd "program files\citrix\web interface\4.0" sitemgr.exe –c "WIDest=894881:/Citrix/MetaFrame,PNADest=894881:/Citrix/PNAgent,XMLService=MPS401:8080;MPS401:8080,Config=MPS401:8080;MPS402:8080" Example 3 – Move Web Interface from the Default Web Site to a new site The following command moves a Web Interface 4.0 site from the Default Web Site to the site whose identifier is 894881: cd "program files\citrix\web interface\4.0" sitemgr.exe –m "WICurrent=1:/Citrix/MetaFrame,WIDest=894881:/Citrix/MetaFrame"

3.3.5 Web Interface for UNIX site creation The JSP variant of Web Interface includes the WebInterface.sh file for creating new sites. The file WebInterface.sh can only be used to create a new site; it cannot be used to move, modify, or delete an existing site. To delete an existing site, remove it from the Web server in the standard way. Option Meaning

WIWARFile=<path> Creates a Web Interface site WAR file at the specified location.

PNAWARFile=<path> Creates a Program Neighborhood Agent site WAR file at the specified location.

MCMWARFile=<path> Creates a MetaFrame Conferencing Manager site WAR file at the specified location.

Config=Local|<service_list>

Where <service_list> is one or more ; separated <server>:<port> pairs.

Specifies the configuration source to be either a local configuration file or the Configuration Service at the specified location(s). If absent, the default is to use a local configuration file.

FarmName=<farm_name> Configures the initial farm to have name <farm_name>. If configuration source is not local, an error occurs. If absent, Farm1 is used.


14

Option Meaning

XMLService=<server>:<port> Configures an initial XML Service at host <server> and port <port>. If configuration source is not local, an error occurs. If absent, the initial XML Service is set to localhost:80.

XMLSProtocol=HTTP|HTTPS|SSL Sets the protocol used to communicate with the XML Service (HTTP, HTTPS or SSL). If configuration source is not local, an error occurs. If absent, defaults to HTTP.

XMLSSSLPort=<port> Sets the SSL port used for communication with the XML Service. If configuration source is not local, an error occurs. Ignored if XMLSProtocol is not SSL. If absent, defaults to 443.

ECS=<server>:<port> Configures an initial ECS service at host <server> and port <port>. If configuration source is not local, an error occurs. Ignored if MetaFrame Conferencing Manager site is not being installed. If absent, defaults to localhost:9000.

ECSSecure=Yes|No Sets whether communications with the initial ECS service are secured using SSL. If configuration source is not local or if no ECS option is specified, an error occurs. If absent, defaults to No.

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

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

15

Web Interface 4.0 Remote Configuration design

The Configuration Manager runs on Presentation Server 4.0 as a DCOM application. It is always installed with Presentation Server 4.0 but only initiates when a request for its services is received. By default, it runs in the process ConfigMgrSvr.exe under the security context of a local account called Ctx_ConfigMgr. If necessary, this identity can be edited using the Component Services snap-in (dcomcnfg.exe):

Web Interface site configurations are submitted to the configuration manager by the Access Suite Console, which loads a .NET assembly called the Configuration Object Library (COL) for these purposes. In order to use a Configuration Manager, the user running the Access Suite Console must be authenticated as a Presentation Server administrator who has been granted the delegated administration privilege called “Log on to Web Interface Console” in the MetaFrame Presentation Server Console:


16

The Configuration Manager interacts with the IMA Service to store configuration files as binary blobs in the IMA database. On startup or after any change has been made to a central configuration file, Web Interface downloads its configuration using the Configuration Proxy. The configuration proxy is similar to the Secure Ticket Authority: it is an ISAPI plug-in that provides a read-only XML interface to the Configuration Manager. It may be hosted by IIS or by the Citrix XML Service; its default path in IIS is /Scripts/CtxConfProxy.dll. Web Interface may be configured with several configuration proxy URLs for failover purposes. Terminology Alert: A Web Interface Configuration Server is not necessarily a Web Interface server, nor vice versa. Only servers running Citrix Presentation Server 4.0 for Windows can act as a Web Interface Configuration Server.

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

17

<ComponentRegInfo key="Technology">ASPX</ComponentRegInfo> <ComponentRegInfo key="PlatformOS">Windows Server 2003</ComponentRegInfo> <ComponentRegInfo key="UpdateURL">http://wisrv/MPS/reloadConfiguration.aspx</ComponentRegInfo> </RequestRegistration> </ConfigProtocol> If the configuration proxy responds with a message saying the site ID is not recognized, then Web Interface posts an XML request that registers the site with the configuration manager. The user will receive an error stating that no configuration is available:

Once the site is registered, a default configuration is created and the site can be edited using the Access Suite Console. For Windows Web servers, the Create site task in the Access Suite Console simultaneously unpacks the site files into the appropriate location and registers the site with the configuration manager if remote configuration is chosen. But for UNIX Web servers, the registration process must take place after the site has been created. Therefore the first request to a new JSP site using remote configuration will always fail. After the first request, the site will have been registered with the configuration manager and the administrator can use the Access Suite Console from any Windows machine to edit the configuration of the JSP site.

3.4.2 Limitations and caveats Communication between Web Interface and the Configration Proxy cannot be

encrypted with SSL. If this traffic must be secured, use IPSec. When entering multiple configuration proxies for failover purposes, it is essential

that all configuration proxies belong to the same Presentation Server 4.0 farm. When creating a new site with the Access Suite Console, the configuration proxies are examined to ensure that they belong to the same farm and an error is returned if not.

If a site is manually copied from one location to another (not recommended), and both the original and the new site are intended to be used simultaneously, you should change the site ID in bootstrap.conf for one of the sites so that they remain unique. In the Access Suite Console, you may also need to edit the apply changes URL to reflect the new site location.


18

3.4.3 Mistakes to avoid When you configure and run discovery in the Access Suite Console, do not enter a

standalone Web Interface server as the name of a Web Interface Configuration Server. If you do, you will receive the following error: The RPC server cannot be contacted on server WIServerName. Only Presentation Server 4.0 can act as a Web Interface Configuration Server.

When running the Access Suite Console from a workgroup server, do not attempt to discover remote sites by contacting a Web Interface Configuration server. If you do, you will receive the following error message: This user account is not a Web Interface administrator for server PSServerName. Discovery of remote sites using a Configuration Server can only be completed when running the Access Suite Console as a domain user who has been granted the “Log onto Web Interface Console” privilege in the Citrix Management Console.

3.4.4 Remote Configuration of Web Interface for UNIX The following steps outline how to install Web Interface for UNIX and create a Presentation Server site that can be configured remotely via the Access Suite Console running on Windows. First, copy WebInterface.sh.gz to your UNIX server (Red Hat Linux Enterprise or Fedora will work). Unzip the archive using gunzip: # gunzip WebInterface.sh.gz Make the script file executable: # chmod a+x WebInterface.sh Run the installation shell script WebInterface.sh: # ./WebInterface.sh

Note that if the sharutils package is not installed, the installation will fail with the following error, citing the absence of uudecode: ./WebInterface.sh: line 175698: uudecode: command not found tar: WebInterface.tar: Cannot open: No such file or directory tar: Error is not recoverable: exiting now ./WebInterface.sh: line 175716: cd: /tmp/WebInterface/WebInterface: No such file or directory Exception in thread "main" java.lang.NoClassDefFoundError: com/citrix/wi/install/UnixSiteTool To install the sharutils package, type yum install sharutils or up2date sharutils.

If sharutils is present, setup begins. Web Interface for MetaFrame Presentation Server Setup

19

Copyright (c) 2004-2005 Citrix Systems, Inc. All rights reserved. This utility prepares the Web Interface for use. You may type Ctrl-C at any time to quit. <Press Enter to view the License Agreement>

The license agreement is shown. Type q to exit the scrolling agreement. Do you agree to the terms of this License Agreement?: yes The following site types are available: [1] MetaFrame Presentation Server [2] Program Neighborhood Agent Services [3] Conferencing Manager Guest Attendee Please specify the type of the site you wish to create [1]: 1 The following configuration sources are available: [1] Local [2] Configuration Service Please enter the configuration source you wish to use [2]: 2 Please enter the next Configuration Service host to contact, or press Enter if there are no more: 192.168.0.104 Please enter the port on which the previously specified Configuration Service is listening. [80]: 8080 Please enter the next Configuration Service host to contact, or press Enter if there are no more:[enter] Please indicate if you want to install the Citrix ICA Clients. You must install the clients for ICA Client download and embedded ICA Client support to work. Install the Citrix ICA Clients? [YES]: no Please enter the path of the WAR file to create [MetaFrame.war]:[enter] SUMMARY Site type: MetaFrame Presentation Server Configured using Configuration Service at: 192.168.0.104:8080; ICA Clients: No Output WAR File: MetaFrame.war The Web Interface will be configured using the information above. Is this OK? [YES]:[enter] Creating the WAR file... All done. Tomcat users: To deploy this web application, please create a directory named Citrix under your Tomcat installation's webapps directory and place the WAR file in it. Then place the context file context-tomcat-metaframe.xml in your Tomcat installation's conf/Catalina/localhost directory. You may edit the context file to deploy this web application to a custom path. BEA WebLogic users: To deploy this web application to a custom path,


20

edit the weblogic.xml within the WEB-INF directory of this WAR file. At this point, a new MetaFrame.war file and corresponding tomcat XML file has been created in the current directory: # ls -l total 12776 -rw-r--r-- 1 root root 665 Apr 8 12:01 context-tomcat-metaframe.xml -rw-r--r-- 1 root root 2150903 Apr 8 12:01 MetaFrame.war -rwxr-xr-x 1 root root 10887457 Apr 7 13:24 WebInterface.sh To deploy this Web application under Tomcat, create the tomcat/webapps/Citrix directory and move the MetaFrame.war file there. Then move the XML file to tomcat/conf/Catalina/localhost/: # mkdir /usr/local/tomcat/webapps/Citrix # mv MetaFrame.war /usr/local/tomcat/webapps/Citrix/ # mv context-tomcat-metaframe.xml /usr/local/tomcat/conf/Catalina/localhost/ Now stop and restart Tomcat to initialize the Web application. # cd /usr/local/tomcat/bin # ./shutdown.sh Using CATALINA_BASE: /usr/local/tomcat Using CATALINA_HOME: /usr/local/tomcat Using CATALINA_TMPDIR: /usr/local/tomcat/temp Using JAVA_HOME: /usr/java/j2sdk1.4.2_08 # ./startup.sh Using CATALINA_BASE: /usr/local/tomcat Using CATALINA_HOME: /usr/local/tomcat Using CATALINA_TMPDIR: /usr/local/tomcat/temp Using JAVA_HOME: /usr/java/j2sdk1.4.2_08 At this point the Web application should be loaded. Point a browser to http://tomcat-server/Citrix/MetaFrame/. By default, Tomcat listens on port 8080, so the URL will be similar to this: http://192.168.0.117:8080/Citrix/MetaFrame/ On the first load, you will receive the following error message, stating that the system configuration is invalid or unavailable:

21

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.


22

4. MetaFrame Presentation Server Site Changes This section describes a few new features and capabilities introduced in the MetaFrame Presentation Server site for Web Interface 4.0.

URL Filtering Language Packs Novell authentication via LDAP Support for Token-only Logins with RSA SecurID 6.0 Getting the Real Client IP from Secure Gateway 3.0

4.1 URL Filtering Web Interface 4.0 includes a built-in URL filter that prevents access to the site’s main scripts until after the user has authenticated. Prior to authentication, the user may not access scripts in the <site-root>/site folder. Instead, the user is directed to the <site-root>/auth folder where authentication is performed.

As such, there exists some apparent file duplication. For example, footer.txt exists in both the auth and site folders. The copy in auth supplies the footer that will be shown prior to user authentication, and the copy in site is the footer for authenticated users. See the Web Interface 4.0 SDK documentation and tutorials in Customizing the Web Interface for a more detailed overview of the Web Interface scripts.

4.2 Language Packs All static strings displayed in Web Interface are drawn from resource files stored in Program Files\Citrix\Web Interface\4.0\languages or <site-root>/languages. On Windows Web servers, the resource files stored beneath Program Files are available to all sites on the server. Storing static strings in resource files makes it easy to change the text on a page without having to navigate the complexity of the scripts. It also makes it easier for Web Interface to support users in multiple languages simultaneously. In the languages folder, *.lang files exist to indicate which languages Web Interface should make available to the user:

• de.lang – German • en.lang – English • es.lang – Spanish • fr.lang – French • ja.lang – Japanese

Each of these files contains a single line, indicating the friendly name of the language, to be shown on the login page and application settings pages. For example, in de.lang: FriendlyName=Deutsch (German)

23

To remove a language from the list, simply delete or rename its corresponding .lang file and then restart the Web service. The collection of static strings is defined in several resource files. For English, the files are:

• common_strings.properties – Strings common to all site types • metaframe_strings.properties – Strings used for MetaFrame Presentation Server

sites • mcmguest_strings.properties – Strings used for MetaFrame Conferencing

Manager sites • mpssourceimpl_strings.properties – Error messages related to MetaFrame

Presentation Server site functionality • pnagent_strings.properties – Error messages related to Program Neighborhood

Agent site functionality • pnagentimpl_strings.properties – More error messages related to Program

Neighborhood Agent site functionality • SslErrorMessages.properties – Error messages for the SSL SDK • webpnimpl_strings.properties – Error messages regarding the internal WebPN

object • xmlclient_strings.properties – Error messages related to communications with

the Citrix XML Service and Secure Ticket Authority This collection of properties files constitutes the English “language pack” for Web Interface. Additional language packs contain the same set of files, but with the language code appended to the file name. For example, the German language pack files are common_strings_de.properties, metaframe_strings_de.properties, etc. Each MetaFrame Presentation Server site includes its own languages folder, which is initially empty. To add a language pack that should be used only for one site, add it to the site’s languages folder instead of the languages folder beneath Program Files\Citrix\Web Interface. The resource files contain static strings, each with a key value assigned. Keys are defined for all visible words (other than application names), including the welcome message, tool tips, client installation captions, and error messages. Here are a few examples: LoginTitle=MetaFrame Presentation Server Login PleaseLogin=Please log in PINRejected=Your PIN could not be set. SettingsError2=Please enter a valid window size. In the scripts, strings are displayed by calling the getString() function with the current locale. For example, the following ASP code would display the text “Your PIN could not be set.”: <%= getString("PINRejected", currentLocale) %> New keys and strings can be added to the resource files if desired. However, simply editing the files with Notepad is not sufficient. The properties files can only be modified by an editor which recognizes the format of Java Properties Files. If you have an editor available that can directly modify Java Properties files, you can use that tool to modify the files. Otherwise, you'll need to follow the instructions below to modify the files in a conventional text editor.


24

• The first step is to convert the Properties files into text files. To do this you need to use the native2ascii tool available from java.sun.com as part of the J2SE Software Development Kit, for example: %JAVA_HOME%\bin\native2ascii -reverse -encoding UTF8 common_strings.properties common_strings.txt

• You can then edit the .txt in a UTF-8 aware text editor. Notepad is capable of

this task. When you have finished modifying a file, you must convert it back into a properties file using the native2ascii tool, for example:

%JAVA_HOME%\bin\native2ascii -encoding UTF8 common_strings_it_IT.txt common_strings.properties

After making changes to the properties file, restart the Web server service in order to make the changes effective.

4.3 Novell Authentication via LDAP In previous versions of Web Interface, the NDS context lookup feature has relied on the NDS client being installed on the Web Interface machine and that machine having access to the NDS server. This feature changes the context lookup so that is it done over LDAP which means that the NDS client is not required on the Web Interface machine. Anonymous bind required by default The supported method of connection to the directory will be anonymous binds. By default, eDirectory does not give anonymous connection access to the cn attribute which is required for contextless login. Administrators have to make changes to the configuration of eDirectory as described in the following Novell article for this feature to function: http://developer.novell.com/research/appnotes/2003/septembe/01/a0309013.htm#1844676 It is also possible to configure Web Interface 4.0 with NDS credentials to make an authenticated bind to the Novell server. To do this, locate the customization point within the file loginNDS.cs: // CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP // // CUSTOMIZATION POINT // // Set ndsAdminUsername and ndsAdminPassword to "" to use anonymous bind // For non-anonymous binds SSL must be used so ensure the following: // - the NDS ceritificate must be in the trusted part of the local // machine's certificate store (use mmc) // - the NDS server name must match the certificate ie. be fully qualified // // CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP string ndsAdminUsername = ""; //"cn=Administrator,ou=company,o=com"; string ndsAdminPassword = ""; //"password"; Note that the connection is made over SSL if you supply a password as eDirectory requires this by default. There are three ways of logging in to Web Interface using NDS credentials:

1. Fully qualified user name – For example, “.user.company.com.” The selection in the context drop down has no effect. The user will be authenticated in the context given as part of the fully qualified user name.

25

2. Non qualified user name with context selected – For example, “user” and “company.com” selected in drop down. The user will be authenticated in the chosen context.

3. Non qualified user name with “Find context” selected – This is the only case where the new context search functionality is used. The entire directory is searched for a user with the given name. If no matching user is found, an error message to that effect is displayed. If exactly one user is found, the authentication is performed against that particular user in that context. If multiple users are found in different contexts, the login page is shown again with the contexts of the users discovered added to the contents of the context drop down. In this case, the user must enter their user name and password again and select one of the contexts to authenticate.

No matter which method is used to select a user name and context, if the configured context list is not empty, the chosen context must be in the configured list otherwise the login is not permitted.

4.4 Support for Token-only Logins with RSA SecurID 6.0 As in previous versions, Web Interface 4.0 supports native integration with the RSA SecurID authentication product. When RSA authentication is enabled, users are prompted for their domain password as well as their RSA passcode:

RSA integrated logon

The RSA passcode consists of a secret PIN code that the user knows, followed by the 6-digit number that appears on the RSA token that has been issued to them:

RSA token

The number shown on the token changes every 60 seconds. The RSA ACE server determines whether a user’s PIN and token code are correct for the given time of day.


26

RSA SecurID 6.0 introduces a new feature that allows users to log in using the RSA passcode only. The domain password is managed and provided by the RSA server—users are not required to know or enter their domain password. Web Interface 4.0 supports RSA 6.0 password integration. To enable this feature, select the “Use Windows password integration” checkbox on the Explicit authentication settings dialog in the Access Suite Console:

Enabling RSA SecurID 6.0 password integration

With this feature enabled, users are prompted to enter only their user name and passcode on the Web Interface login page:

27

How it works The Web Interface server scripts responsible for user authentication include functions to validate an RSA passcode. RSA 6.0 with Windows password integration follows this process:

RSA SecurID 6.0 Integrated Password Authentication

1. Client accesses the Web Interface server and is prompted for their user name and passcode.

2. Web Interface calls on code in <site-root>/auth/bin/Authenticators.dll to instantiate an RSA client object and authenticate the user’s passcode. The passcode is encrypted and sent to the RSA ACE server using UDP port 5500. If the passcode is correct, the RSA Server sends the user’s domain password back to Web Interface.

3. Web Interface receives the user’s domain password from the RSA 6.0 server and sends it to the XML Broker. The explicit authentication process follows normally from there.


28

5. Core Feature Specifications This section explains how a few of the main Web Interface features are implemented.

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

5.1.1 Explicit Authentication Explicit Authentication refers to the mode of authentication where the user must type their user name and password into a web form in order to gain access to published applications. Explicit authentication is performed against a Windows domain or a Novell eDirectory tree, and may be augmented to require an RSA SecurID or Secure Computing SafeWord passcode in addition to the user’s domain password.

How it works Web Interface produces a login form asking for a user name and password. A domain value is also required, but may be supplied by the administrator.

When users click the Log In button, their credentials are posted to the Web server using standard HTTP or HTTPS. It is important to secure the Web Interface server with HTTPS--otherwise a user’s password from the POST request will be visible on the network: POST /Citrix/MetaFrame/default/login.aspx HTTP/1.1 Content-Type: application/x-www-form-urlencoded User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; .NET CLR 1.1.4322) state=LOGIN&LoginType=Explicit&user=jayt&password=secret&domain=TOMLIN&login=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:

29

<NFuseProtocol version="4.2"> <RequestAppData> <Scope traverse="onelevel"></Scope> <DesiredDetails>defaults</DesiredDetails> <DesiredDetails>file-type</DesiredDetails> <ServerType>all</ServerType> <ClientType>ica30</ClientType> <ClientType>content</ClientType> <Credentials> <UserName>jayt</UserName> <Password encoding="ctx1">MPGKPGFDILDOPOFLIMCJLPBK</Password> <Domain type="NT">TOMLIN</Domain> </Credentials> <ClientName>WI_1gykQ6/J7yKTj1ooSxKn</ClientName> <ClientAddress addresstype="dot">192.168.0.152</ClientAddress> </RequestAppData> </NFuseProtocol> This traffic may be secured using SSL Relay, but note that the password is no longer in clear text here; it is scrambled, but this is not considered strong encryption. Before the XML Broker returns applications for the user, the credentials must be validated. This task is delegated to the IMA Service, which in turn calls LogonUser() and LookupAccoutSid() from the local security account subsystem in Windows (LSASS.EXE).

Explicit user authentication

1. User sends credentials to Web Interface via HTTP POST command. 2. Web Interface includes credentials as part of the application enumeration

request. 3. The XML Service delegates user authentication and application enumeration to

the local IMA Service, which ultimately makes calls to the local security authority (LSASS).

Novell integration When integrating with Novell NDS, Web Interface attempts to perform contextless logins by locating the user object within the NDS tree. For this action to succeed, the Web Interface server must be able to contact a Novell NDS server on TCP port 389 (LDAP). By


30

default, Web Interface searches the entire tree until it finds a user object matching the current user name. To restrict this search to a limited number of contexts, enter the contexts into the Access Suite Console.

For more information about integrating with Novell NDS, see article CTX101898. The article was written for MetaFrame XP Feature Release 2 and NFuse Classic 1.7, but the Novell integration features in Web Interface have not changed since then.

How it breaks Policy settings at the XML Broker prevent logon Because the user authentication task is deferred to the local operating system at the XML Broker, explicit logins should work as long as the user is able to log on locally at the XML Broker server. To confirm this, make an ICA or RDP connection directly to the XML Broker desktop and attempt to log on using the standard Windows GINA. Any problems that occur using the standard GINA, such as issues with custom redirectors or the inability to locate a domain controller, will similarly affect Web Interface authentication. However, keep the following in mind when testing logins at the XML Broker:

• Enumerating farm icons with the Program Neighborhood client from the Web Interface server is not a valid test of the user’s ability to log on. Program Neighborhood only uses the XML Service to locate the least-busy server in the farm and then makes a headless ICA connection to the least-busy server where user authentication takes place.

• If the XML Broker is a Windows 2003 server, it is possible that the user does not have the “Allow log on through Terminal Services” right. In this case an RDP or ICA session test would fail even if the user does have Log On Locally rights. Users do not need the “Allow log on through Terminal Services” privilege on the XML Broker in order to enumerate icons.

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

Known limitations and issues • If the MetaFrame XML Broker is also a Windows 2000 or Windows 2003 domain

controller, only users who belong to the Domain Administrators group are able to authenticate by default. To repair this problem, edit the policy for that MetaFrame server and grant all users the Log On Locally privilege.

• Novell NDS authentication is available with Windows Web servers only.

Frequently Asked Questions Does the XML Broker server have to be a domain controller? No, the XML Broker will locate an appropriate domain controller for the supplied credentials. For best results, place a domain controller on the same network segment as the MetaFrame farm. Does the XML Broker server have to be an IMA zone data collector (ZDC)? No, but performance is improved if the XML Broker is a ZDC. User authentication does not require the services of a ZDC but locating the least-busy server when the user clicks

31

an application does. If the XML Broker is not a ZDC, application address requests are forwarded to the data collector of the zone in which the XML Broker resides. Can an XML Broker that belongs to Domain A authenticate a user from Domain B? Yes, as long as Domain A trusts Domain B. This is no different from logging in through the standard Windows GINA as discussed above. Users are being forced to reauthenticate every 20 minutes. How do I change this session timeout? Because the session is controlled by the .NET runtime instead of IIS, changing the session timeout value in Internet Services Manager as discussed in CTX191516 does not affect Web Interface 3.0. Instead, you should add a sessionState element to the <system.web> section of web.config declaring a new timeout in minutes. For example, to change the session timeout to one hour, add the following line to /Citrix/MetaFrame/site/web.config: <configuration> <system.web> <sessionState timeout="60" /> <compilation debug="false" defaultLanguage="C#"> <assemblies> Note: Web.config entries are case sensitive and take effect immediately. Use sessionState, not sessionstate.

5.1.2 Single sign on This feature, formerly referred to as “Desktop Credentials Pass Through” allows users to authenticate to the Web Interface using their Windows desktop login credentials. Authentication to the Web server is similar to the authentication that occurs when a domain user accesses a file share or domain print server to which they have been given access: the user’s Windows credentials need not be reentered. Instead, the user simply accesses the Web Interface site and their applications are displayed immediately.

How it works 1. The user begins by accessing the default URL for Web Interface. 2. Web Interface triggers an Integrated Windows Authentication challenge/response

handshake between the Web browser and IIS. 3. After a successful Integrated Windows authentication, IIS impersonates the

authenticated user to produce a list of domain groups to which the user belongs. The AUTH_USER server variable will be populated with the authenticated domain name and user name (for example, AUTH_USER=“TOMLIN\jayt”).

4. Web Interface uses this information to enumerate applications.

How it breaks Restricted NTFS permissions After successfully negotiating Integrated Windows Authentication, IIS impersonates the current user account when accessing files on the Web server’s hard drive. Compare this to anonymous authentication, where IIS impersonates the IUSR account in order to access local resources. This design mandates that the user’s domain account have at least Read permission on all scripts beneath the Web server’s document root directory. Therefore, administrators who restrict NTFS permissions on the files beneath wwwroot to allow access only by Administrators or the IUSR account will find that non-administrator users are unable to view Web Interface pages.


32

To correct this problem, ensure that in addition to the IUSR account, all users who will access the Web Interface have NTFS read permissions on all files beneath wwwroot/Citrix on the Web server. Proxy servers disrupt Integrated Windows authentication If you attempt to access the Web Interface via an HTTP proxy server, the NTLM challenge/response authentication required for single sign on will likely fail. Integrated Windows authentication is generally not possible through proxy servers, including the case where HTTPS traffic is proxied through Secure Gateway en route to Web Interface. See the Microsoft TechNet Web site for details. To resolve this issue, bypass the proxy server or use HTTPS to the IIS SSL port.

Known limitations and issues • Not available with Web Interface for UNIX. • Web Interface IIS server must be a member of the client domain or a trusted

domain. • Requires Internet Explorer for Windows on the client. • If the Web server is not in the client’s Trusted Sites zone, Internet Explorer will not

complete the Integrated Windows Authentication handshake automatically. Instead, the user receives a pop-up authentication window from IE requesting their user name, password and domain. Web servers addressed as a NetBIOS host name are trusted by default; those addressed as a fully-qualified domain name or IP address are untrusted by default.

5.1.3 Smart Card Authentication Smart card authentication is very similar to single sign-on authentication: IIS authenticates the user and then enumerates applications using a list of group SIDs instead of the user’s explicit user name and password. To authenticate the user, IIS relies on client certificate mapping.

How it works A user is provided with a smart card reader and is issued a smart card containing a user certificate and private key. In order to access the private key stored on the smart card, the user must provide their PIN code, usually a 4-digit number. Any Web site or virtual directory served by IIS can be configured to accept or require client certificates:

33

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:


34

Enable the Windows directory service mapper

By default, this feature is not enabled in IIS. Once a successful account mapping has been made, the domain controller returns a token for the identified user and IIS impersonates the user’s domain account for script access. More information about client certificate mapping in IIS is available from the Microsft TechNet Web site.

How it breaks IIS is misconfigured If the metabase settings on the certificate virtual directory are modified so that client certificates are no longer required or client certificate mapping is not enabled, Web Interface cannot authenticate the user. To correct this problem, use the Repair option for the site in the Access Suite Console.

Known limitations and issues • Requires the server running Web Interface to be a member of an Active Directory

domain and have connectivity to a domain controller • Smart card authentication is not possible when Secure Gateway (or anything else)

acts as an SSL-terminating reverse proxy for Web Interface. Users must make an HTTPS connection directly to the IIS SSL listening port.

• Not available with Web Interface for UNIX • Not available with NT4 domains

35

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.

5.1.4 Change password This feature allows end users to change their Windows or NDS password (but not both simultaneously) through a Web form provided by Web Interface when users click the key icon:

Change password dialog

How it works The task of changing a user’s password is deferred to the XML Service running on Presentation Server. This relieves the Web server from needing any ties to the user’s domain; the Web server can belong to a workgroup in the DMZ with no connectivity to a domain controller or be running on the Linux or Solaris platform and still facilitate Windows NT4, Active Directory, or Novell NDS password changes. On the Presentation Server, code in CTXADMIN.DLL services the password change request. The old and new passwords are sent from Web Interface to CTXADMIN.DLL via the Citrix XML Service. For example: POST /scripts/ctxadmin/ctxadmin.dll HTTP/1.1 <AdminProtocol version="4.2"> <RequestChangePassword> <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


36

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).

Known limitations and issues • Not available with MetaFrame for UNIX, MetaFrame 1.8, or MetaFrame XP Service

Pack 1 and earlier • Fails on MetaFrame XP Service Pack 2/Feature Release 1 for NT 4.0, Terminal Server

Edition with the error “405 Method not supported”

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

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

How it works for explicit authentication

Explicit application enumeration

1. Web Interface sends a <RequestAppData> command to the XML Broker asking for the list of applications for the current user and their default settings:

<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>

37

<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>


38

<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> Multiple <RequestAppData> commands may need to be fulfilled in order to collect all application icons (each request will ask for a maximum of five icons). Icon graphics are retained in memory on the Web server and will not be requested again unless the application sequence number changes. Application settings on the other hand are requested every time a user logs on.

How it breaks In most cases a failure to enumerate applications represents an authentication problem at the XML Broker. In rare cases though, the user may authenticate successfully but not receive the full list of applications that they were expecting, or they may see (but not be able to launch) applications to which they have not been given access. These issues are most likely

39

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.

Known limitations and issues • If the XML Service fails to respond, the Web server enumeration script times out

(CTX101691)

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

How it works for Single Sign On or Smart Card Authentication When configured for Single Sign On or Smart Card authentication, Web Interface detects the user’s existing Windows domain authentication and enumerates applications for that user automatically, without requiring the user to provide their user name and password.

1. IIS, having authenticated the user using Integrated Windows Authentication, is able to identify the user’s domain and user name, but not their password. Therefore a normal enumeration of application icons is not possible as it is with explicit enumeration. Instead, the Web server determines the list of domain groups to which the user belongs using functionality available in SidEnumerator.dll. Web Interface constructs an XML request containing all of the user’s individual and group SIDs and forwards this list of SIDs to the MetaFrame XML Broker. For example:

<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>


40

2. The XML Service queries IMA to obtain the list of applications that have been

published to the user or any of the groups in the list. Note that the XML Broker does not perform user authentication at this point, as the user’s password is still unknown.

3. The list of applications and their icons is returned via XML to Web Interface.

How it breaks If a user does not have the Program Neighborhood client installed with the “Use local credentials to log on” option selected, then they will be able to enumerate applications at Web Interface but will be prompted for a password when they launch an application.

Single sign-on to MetaFrame Presentation Servers

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

Known limitations and issues • Not available with MetaFrame for UNIX or Web Interface for UNIX. • Requires all aggregated farms to be running MetaFrame XP Service Pack 2 or

later. A Feature Release 2 license is not required. (CTX811426) • In an attempt to prevent overflow attacks, the XML Service limits the size of

requests that it will accept to 4096 bytes by default. If a user belongs to a large number of groups, the size of their SID list may exceed the XML Service request

41

limit. See CTX943036 for information about hotfixes and a registry flag that can be set to increase the maximum XML request size.

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

5.3 Determining the target MetaFrame server address Web Interface fosters connections to the most appropriate, least busy MetaFrame Presentation server whenever a user clicks an application icon.

How it works When a user clicks an application icon, Web Interface sends a request to the XML Broker asking for the address of a target MetaFrame server to which the user should connect. Web Interface will ask for the normal or the alternate server address depending on which addressing method has been determined for the current client IP. For example: <RequestAddress> <Name> <AppName>Microsoft Outlook</AppName> </Name> <ClientName>WI_Ucs/237RBAKqj9tf</ClientName> <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.


42

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. DNS address not returned or not the expected result Web Interface can be configured to request fully-qualified domain names instead of IP addresses for MetaFrame Presentation servers by setting AddressResolutionType=DNS or DNS-port in WebInterface.conf. However, unless the MetaFrame farm is configured to enable XML Service DNS name resolution, server addresses will continue to be reported as IP addresses. In other cases, only a server host name or a different domain name is returned instead of the expected fully qualified domain name. This occurs when the target MetaFrame server is configured with a static IP address and no default domain suffix is configured for that server. This can cause SSL Relay connections to fail because the name of the server sent to Web Interface does not match the subject of the certificate used by the SSL Relay service. To resolve this issue, set the domain name in the Network Identification tab in the System Properties for the target MetaFrame Presentation server. (CTX101535) No alternate address found If Web Interface is configured to request the alternate address of MetaFrame Presentation servers but an application is published on a server where the alternate address has not been defined, Web Interface cannot produce an ICA file. To resolve this issue, set an alternate address on the target server using ALTADDR.EXE, for example: altaddr /set 206.81.35.76

43

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"; }

Known limitations and issues • MetaFrame 1.8 servers require a Feature Release 1 license or later in order to

use DNS address resolution


44

• If the target server is not MetaFrame XP Feature Release 1 or later, only the IPv4 address resolution type is supported

Frequently Asked Questions When should you enable DNS address resolution in WebInterface.conf? There are two scenarios where DNS address resolution is needed:

1. SSL Relay - The SSL Relay service must be configured to use a certificate whose subject matches the FQDN of the MetaFrame server, and clients must connect using the FQDN. Attempting to connect by IP address will cause an SSL error.

2. Multiple NAT firewalls - In some networks, there might be multiple client networks which have to traverse a NAT firewall in order to reach the MetaFrame Presentation Server farm. If there were only one such client network then using ALTADDR would suffice, but there can be only one alternate address per NIC on the MetaFrame server so a different solution is needed when there is more than one NAT firewall. For these cases, you can enable DNS name resolution and then each client network can add a local DNS entry that resolves the MetaFrame server FQDN to the appropriate NAT firewall address. This allows connectivity through an arbitrary number of NAT firewalls, since each client network can resolve the FQDN to a different IP address.

5.4 NFuse Ticketing NFuse Ticketing refers to the generation of a single-use, time-sensitive ticket that authenticates the user to a Presentation server instead of using their user name and password. History NFuse version 1.0 did not include a ticketing feature, and rendered ICA files contained the user’s scrambled password. Though the password was not readable, the ICA file could be reused to gain access to the farm. Ticketing was introduced in NFuse 1.5 to eliminate this security risk. It enables the production of ICA files that contain no reusable authentication information. Once a ticket has been redeemed it can never be used again. If the ticket is not used within a configurable timeout, it expires and cannot be used. NFuse Ticketing is similar to, but not the same as Secure Gateway Ticketing.

45

How it works

NFuse Ticketing

1. The user provides their user name, domain, and password to the server running Web

Interface and clicks an application icon. Web Interface sends a <RequestAddress> command to the XML Broker to determine the address of the MetaFrame target server. The target server will be the least busy server in the farm hosting the selected application unless the user already has a disconnected session for that application on some other server.

2. A ticket request is constructed by Web Interface that includes the user’s credentials. The password is scrambled using simple XOR encoding. The desired ticket timeout, defined by the TicketTimeout parameter in WebInterface.conf, as part of the ticket request. Example:

<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>

This request is sent to the MetaFrame XML Broker.

3. The XML Broker forwards the ticket request to the target server.


46

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.

5. The XML Broker returns the ticket to Web Interface.

6. The ticket is incorporated into the launch.ica file and delivered to the user’s Web browser. The ticket is divided into two halves and placed into the Domain and ClearTextPassword ICA file parameters:

Username=jayt Domain=\176A89579BC384D8 ClearPassword=A4C8832C879768

The backslash character preceding the domain name is a signal to WinLogon that the credentials being presented are to be interpreted as a ticket rather than an actual domain name and password.

7. The ICA file is executed by the client, and the user initiates an ICA connection to the target Presentation server. The ticket is presented to the logon GINA instead of a domain and password. Winlogon.exe loads CCTICKET.DLL and is able to locate the user’s real credentials which are still waiting in memory. The user’s real credentials are retrieved from memory and submitted to the WinLogon process. Note - If for any reason the credentials in the ticket request were invalid, failure would not occur until after the WinLogon substitution. CCTICKET.DLL does not validate credentials before producing a ticket.

How it breaks Generally speaking, NFuse Ticketing fails whenever the XML Service on the target MetaFrame server is unreachable or if the target server is not licensed for ticketing.

Known limitations and issues 1. Requires a minimum of MetaFrame 1.8 with Service Pack 1 and a Feature Release 1

license on all servers in the farm. 2. See CTX101303 for a list of issues that affect ticketing. 3. If a MetaFrame farm contains a mix of servers running MetaFrame Presentation

Server 3.0 and MetaFrame XP Feature Release 3 or earlier (not recommended), then the XML Broker must be configured to send ticket requests to the XML Service on the target server instead of using the IMA Service.

47

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.

5.5 Address Translation Users from various locations may access a single Web Interface server. Depending on their location, the users may have different addressing needs for making the ICA connection to a MetaFrame Presentation Server. For example, users on the corporate network where the Presentation servers themselves reside are able to connect to the Presentation server’s real IP address, while users from a satellite office or partner network may have to connect through a Network Address Translation firewall:

Alternate addressing scenario

Or, Web Interface may be configured to use Secure Gateway to enable access from the Internet, while internal users should still connect directly to MetaFrame without traversing the gateway:


48

Secure Gateway addressing scenario

Because Web Interface is responsible for fostering ICA connections for all users, a determination must be made to use an appropriate addressing method for any given user based on their location. The Web Interface administrator configures address translation preferences using the Access Suite Console or by manually editing WebInterface.conf. There are a total of six unique addressing methods:

1. Direct – Use the real address of the MetaFrame server, for example, Address=192.168.0.98:1494.

2. Alternate – Use the alternate address of the MetaFrame server as configured by running ALTADDR.EXE on each Presentation server, for example, Address=206.31.24.99:1494.

3. Translated – Similar to Alternate, but the translated address and port for each MetaFrame server are defined by Web Interface server in the Port Address Translation table instead of by running ALTADDR.EXE on each Presentation server, for example, Address=206.31.24.99:4000.

4. Secure Gateway Direct – The client connects to Secure Gateway, then Secure Gateway forwards traffic to the MetaFrame Server’s normal address.

5. Secure Gateway Alternate – The client connects to Secure Gateway, then Secure Gateway forwards traffic to the MetaFrame Server’s alternate address. Use this method if a NAT firewall separates the gateway from the MetaFrame Presentation servers.

6. Secure Gateway Translated – The client connects to Secure Gateway, then Secure Gateway forwards traffic to the MetaFrame Server’s translated address. Use this method if Port Address Translation is required between the gateway and the MetaFrame Presentation servers.

See the sections on Secure Gateway Integration and Secure Gateway Ticketing for more details about using Secure Gateway with Web Interface.

49

How it works The location of the client is determined by an HTTP environment variable called REMOTE_ADDR. All Web servers maintain a REMOTE_ADDR value for each HTTP session. REMOTE_ADDR is determined by inspecting the TCP return address of the HTTP packet that arrives at the Web server. Important: REMOTE_ADDR may or may not be the end user’s IP address. When a client access the Web server directly, REMOTE_ADDR will equal the client’s IP address; but if the client’s traffic passes through any proxy servers, gateways (including Secure Gateway for MetaFrame) or proxy-based firewalls, REMOTE_ADDR will be the firewall or proxy address whose interface is nearest to the Web server. See CTX101993 for a discussion on how Secure Gateway can affect REMOTE_ADDR.

5.5.1 Getting the Real Client IP from Secure Gateway 3.0 When Secure Gateway proxies HTTP traffic to Web Interface, all users appear to have the same client address: the address of the Secure Gateway server. In order for Web Interface to distinguish internal from external users, Web Interface needs to learn the client’s real IP. This was not possible in Secure Gateway 2.0 (see this forum thread for more details), but can be achieved with Secure Gateway 3.0. Before proxying a Web request to Web Interface, Secure Gateway 3.0 adds an HTTP header called X-Forwarded-For set equal to the value of the client address as the gateway sees it. (This may still not be the real client address depending on proxy servers and firewalls.) Within the user’s session on the Web Interface Web server, this value will be available as the server variable HTTP_X_FORWARDED_FOR. Logic can therefore be added to the Web Interface scripts to use HTTP_X_FORWARDED_FOR instead of REMOTE_ADDR whenever HTTP_X_FORWARDED_FOR is present and REMOTE_ADDR equals 127.0.0.1 (or the IP address of the gateway when Web Interface and Secure Gateway are on separate servers). For example, if Web Interface 4.0 and Secure Gateway 3.0 are installed on the same server, locate the following code in <site-root>/auth/serverscripts/include.cs and <site-root>/site/serverscripts/include.cs: /** * Returns the IP address of the client. */ public string getClientAddress() { return Request.ServerVariables["REMOTE_ADDR"]; } Change both copies to: /** * 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"]; } }


50

If Secure Gateway and Web Interface are on separate servers but Web Interface is deployed behind Secure Gateway, change the address 127.0.0.1 in the above code to match the IP address of the Secure Gateway server as Web Interface sees it. Note that a similar change could be implanted on Web Interface 3.0 or earlier as long as Secure Gateway 3.0 is used as the reverse proxy.

5.5.2 Address Translation Logic The following flowchart illustrates the logic used by Web Interface to determine which of the six addressing methods should be used for the current user:

51

Address Translation Logic in Web Interface


52

How it breaks Most cases where address translation appears to be malfunctioning are caused by confusion over the client address. For example, an administrator wishes to use Secure Gateway for all external users coming from the Internet and normal addressing for all internal users who reside on the 10.0.0.0 network. So the administrator makes what seems to be the right configuration: ClientAddressMap=10.0.0.0/255.0.0.0,Normal,*,SG This setting tells Web Interface to use Normal addressing for anyone whose IP address begins with 10 and Secure Gateway for anyone else. But the administrator reports that users on the Internet are being directed to the MetaFrame server’s internal address (which fails) instead of being sent through the gateway. Upon inspecting the value of REMOTE_ADDR by loading the debug.aspx file, we find that all Internet users are arriving at the Web server with the same address and it begins with 10! This occurs because their HTTP traffic is passing through secure gateway, a reverse HTTP proxy or a proxy-based firewall. Therefore REMOTE_ADDR will be the firewall or gateway address instead of the client’s true address. Continuing the example above, suppose we find that external users always show REMOTE_ADDR=10.9.41.62, the internal interface of the customer’s Microsoft ISA Server. We would therefore reverse the address translation logic to establish Normal addressing by default and use the firewall address to define an exception for external users: ClientAddressMap=10.9.41.62/255.255.255.255,SG,*,Normal See CTX101993 and the forum thread at http://support.citrix.com/forums/thread.jspa?forumID=5&threadID=40069 for more examples. For versions of Web Interface prior to 3.0, use the debug.asp page from CTX052061 to expose the value of REMOTE_ADDR.

5.6 Workspace Control Workspace Control allows the user to perform the following actions from Web Interface: • Disconnect from all active Presentation Server sessions • Log out of all active Presentation Server sessions • Reconnect to all currently disconnected Presentation Server sessions • Reconnect to any currently active Presentation Server sessions

How it works Workspace control features are implemented in large part by the XML and IMA Services in Presentation Server version 3.0 and later. Disconnecting from all applications When the user clicks the Disconnect button beneath their application set, an XML request is sent to MetaFrame asking the XML Broker to disconnect all current sessions for this user. Web Interface does not attempt to track which applications the user has launched; instead it defers the enumeration and disconnection of current sessions to IMA.

53

Steps to disconnect or logoff ICA sessions

1. User clicks Disconnect or Logoff. 2. Request is forwarded to XML Broker along with user’s credentials. 3. XML Broker uses IMA to locate all sessions belonging to that user and issue the

Disconnect or Logoff command. 4. Presentation servers respond with IMA success message. 5. Success message returned to Web Interface. 6. User is logged out and returned to the Web Interface Login page.

The disconnect.aspx script produces an XML request document containing a <RequestDisconnectUserSessions> element such as the following: <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>


54

</NFuseProtocol> The IMA Service on the XML Broker server initiates a DisconnectUserSessions() command, which publishes the event to all servers in the farm and instructs them to disconnect the user’s session. Reconnecting to applications When the user logs on to Web Interface with the Reconnect option enabled, or whenever they click the Reconnect button beneath their application set, the script reconnect.aspx is executed.

Steps to reconnect ICA sessions

1. User clicks Reconnect or logs on with Reconnect enabled. 2. Request forwarded to XML Broker along with user’s credentials. 3. XML Broker uses IMA to locate all disconnected sessions belonging to that user. If

the user wishes to be reconnected to active sessions as well, a disconnect request is sent over IMA to any server where the user has an active session.

4. XML Broker returns a list of sessions to Web Interface. 5. Web Interface returns a hidden frameset containing links to each disconnected

application. 6. The client automatically requests each application. From this point a normal

reconnection process takes place. 7. Client’s credentials are forwarded to XML Broker. 8. XML Broker requests ticket from target MetaFrame server(s). 9. Address and ticket belonging to target server returned to Web Interface. 10. Web Interface delivers ICA file to client. 11. Client makes ICA connection to target server and resumes the disconnected ICA

session.

55

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. Given the list of disconnected sessions, reconnect.aspx produces an HTML frameset which is loaded into the hidden frame called “hiddenwindow2”: <frameset cols="100" border="5" framespacing="20" frameborder="yes"> <frame src="launch.ica?NFuse_Application=Farm1x003aNotepad&NFuse_AppFriendlyNameURLEncoded=Notepad&NFuse_HostId=9914&NFuse_HostIdType=imax002dhostx002did&NFuse_SessionId=2" name="Reconnect0" title="Reconnect0" scrolling="yes" frameborder="yes" border="1"


56

> </frameset> The effect of this hidden HTML frameset is the same as clicking an application icon: an ICA file is requested from Web Interface and the normal reconnection process ensues. A similar frame tag is generated for each session to which the user should reconnect. Untrusted XML Service Logoff, disconnect, and reconnect actions are security critical events that should be password protected. When Web Interface or Program Neighborhood Agent calls these commands they forward the user name and password provided by the end user for the sessions they intend to disconnect or logoff. This causes problems for smart card and single sign-on configurations because Web Interface does not have access to the user’s password in these configurations. Allowing the commands to run without a password by default opens a security vulnerability whereby an attacker who brings up their own Web Interface server in a different domain could reconnect to your sessions. To prevent this sort of attack, logoff, disconnect and reconnect requests sent to the XML Service are untrusted (i.e. they require the user’s password) by default. To enable trust, run the Citrix Management Console and edit the properties of the server acting as XML Broker for Web Interface. Select Workspace Control property and enable the checkbox for “Trust requests sent to the XML Service”:

Enable trust for workspace control

Administrators should restrict access to a trusted XML Service using firewalls, IPSec, port filtering, or any other method they see fit. Only authorized Web Interface servers should be allowed to connect to a trusted XML Service. Secure the network before enabling trust. Windows 2000 Domain Controller + IIS Port Sharing cannot be used as XML Broker When the XML Broker providing data to Web Interface is a Windows 2000 Domain Controller using IIS port sharing to deliver the XML Service, workspace control actions fail with an unspecified error. To resolve this issue, do not use IIS port sharing. Register the XML Service on a separate port by running the following commands: ctxxmlss /r8080

57

net start CtxHttp Then reconfigure Web Interface to use the new port for the XML Service communication.

Known limitations and issues • Workspace Control requires MetaFrame Presentation Server 3.0 for Windows

Advanced or Enterprise Edition and Web Interface 3.0 or later. • On Win32 systems, if a native ICA client is present, workspace control features are

enabled only if the client version is 8.0 or later; if no native ICA client is present then the workspace control features are enabled only when using the Client for Java.

• Workspace control functions are disabled when running the ICA Client in pass-through mode (for example, when you connect to a published instance of Internet Explorer, then point to Web Interface).

• Some WinCE devices cannot support multiple instances of the ICA client, or if they can, do not offer any way to switch between them. Session reconnect in situations where there are multiple sessions involved will therefore be problematic.

• The process of reconnecting to an active session involves temporarily disconnecting the session just before the user reconnects. If a MetaFrame server is configured to reset disconnected sessions immediately, reconnecting to active sessions on that server will fail.

• If a user has multiple non-seamless sessions running the same application on the same server, they will be presented with a dialog upon reconnect asking which session they would like to be reconnected to.

• Applications published for anonymous use are terminated when both anonymous and authenticated users log off. Thus, users cannot reconnect to anonymous applications after they log off.

• Workspace control features do not appear in Netscape if Netscape was installed after the ICA client. You must install Netscape first, then install the ICA client.

• When using an embedded ICA client (Java or ActiveX), workspace control reconnects may be suppressed by pop-up blocking software.

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


58

What happens if I already have sessions running on multiple client devices? The Disconnect and Logoff features will not affect other sessions that are already running on other client devices, but the Reconnect feature will consolidate all your sessions onto the current client device. Does this feature work with the Program Neighborhood client? Because the feature is implemented by Web Interface, it only works through a Web browser or with the Program Neighborhood Agent client. Do the workspace control buttons affect sessions that were initiated using Program Neighborhood? The Disconnect and Logoff buttons only affect applications that were launched using Web Interface from the current workstation, but the Reconnect button can reconnect you to published applications that were initiated in any way from any workstation. Custom ICA connections to server desktops are not affected.

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

5.7 Using Secure Gateway with Web Interface Web Interface can render ICA files for users that direct them through a Secure Gateway server en route to their applications. After authenticating to the Web server and selecting a published application, users connect to a gateway server instead of the target Presentation server. The gateway acts as an ICA traffic relay between the client on an untrusted network and a MetaFrame Presentation Server on the trusted network. ICA traffic between the client and the gateway is encrypted using 128-bit SSL or TLS.

59

Secure Gateway solution architecture

The Secure Gateway Administrator’s Guide discusses the secure gateway solution in detail. The purpose of this section is to examine how Web Interface enables secure gateway connectivity.

Note that the Secure Ticket Authority is integrated into the Citrix XML Service with Presentation Server 4.0, and may therefore be consolidated with the MetaFrame XML Broker in the diagram above. To define the Secure Gateway FQDN and STA location(s) in Web Interface, select Manage Secure Client Access > Edit Secure Gateway Settings in the Access Suite Console:

Edit Secure Gateway Settings


60

In the dialog that appears, enter the fully qualified domain name of the gateway, which should match the subject of the certificate installed on the gateway. Remote clients must be able to resolve this FQDN to the external IP address of the Secure Gateway server(s). Enter one or more Secure Ticket Authority URLs of the form http://sta-server/Scripts/CtxSta.dll.

Secure Gateway Settings Defined in the Access Suite Console

Once the gateway FQDN and STA URLs are defined, enable Secure Gateway connectivity by creating address translation rules in the DMZ settings to direct some or all of your users through the gateway. To do so, select Manage Secure Client Access > Edit DMZ Settings:

61

Edit DMZ settings

Change the default connection method to Secure Gateway Direct. You may also wish to add an exception rule that allows users on the trusted network to bypass the gateway and connect directly to Presentation Servers:

Address Translation Rules in Web Interface 4.0

How it works The following diagram illustrates the process by which Web Interface produces an ICA file intended for use with Secure Gateway:


62

Secure Gateway Connection Process

1. Having authenticated to Web Interface, the user clicks an application icon. 2. Web Interface contacts the XML Broker to determine the address of the target

MetaFrame server. 3. The XML Broker locates the least-busy server for the chosen application and

requests a MetaFrame Logon Ticket for that server. 4. The address of the target MetaFrame server and a corresponding MetaFrame

Logon Ticket are returned to Web Interface. 5. Web Interface sends the target server address, user name, domain name and

published application name (collectively referred to as “the data”) to the Secure Ticket Authority (STA) and gets a gateway traversal ticket in return.

6. Web Interface renders an ICA file for the user containing the gateway traversal ticket in the Address field. Also included in the ICA file are the following lines that instruct the client to connect to a gateway: SSLEnable=On SSLProxyHost=csg.company.com:443 The fully-qualified domain name of the Secure Gateway server is drawn from the CSG_Server value in WebInterface.conf.

7. The client makes an ICA-in-SSL connection (not HTTPS!) to the gateway server on port 443 and performs an SSL handshake. The gateway server sends its server certificate chain to the client; the client must have the appropriate CA root certificate in order for the SSL handshake to succeed.

8. The gateway server extracts the gateway traversal ticket from the user’s ICA file and sends it to the STA for redemption. The gateway receives the data from the STA corresponding to the current ticket. The ticket is then purged from the STA’s memory immediately.

9. Having validated the user’s ticket, the gateway opens a TCP connection to the MetaFrame server’s ICA port and forwards decrypted ICA traffic to the server. A relay is established with the gateway providing encryption/decryption service between the client and the target MetaFrame server. The MetaFrame Logon Ticket is supplied to initiate the ICA session without reauthentication.

63

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)."

Known limitations and issues • Web Interface supports the definition of only a single secure gateway FQDN. The

ability to route users through different gateways based on farm, application name or user location is possible only through custom script development.


64

6. Troubleshooting techniques This section discusses various tips and techniques for troubleshooting Web Interface problems.

6.1 Event-based logging Web Interface 4.0 provides a logging facility to improve troubleshooting and fault diagnostics and increase system security. Instead of providing detailed system error messages to the user (which at best can confuse them, and at worst could be used to gain knowledge of the system for malicious purposes), users will only receive one of a few generic system error messages, which describe the basic classification of the problem. Detailed system error descriptions including errors reported by the underlying system along with some form of identifiers (for example, a combination of user name, timestamp, and event id) are logged into the Windows “Application” event log for IIS and the Servlet engine log files for JSP. The log identifiers for system errors will be displayed to the users along with the generic error messages so that the former can be passed to administrators for easier identification in the log. Web Interface monitors the log entries it writes out over time. This is so that it can control the number of duplicate log entries that are written for a single event and not fill up the server log in the event of large-scale failure. This is for both ASP.Net and JSP deployments. The new configuration settings for this functionality are as follows:

• DuplicateLogInterval • DuplicateLogLimit

The system behavior will be such that if DuplicateLogLimit duplicate log entries have been written in a time period DuplicateLogInterval then further attempts to log the same message will not be committed to the server log. Errors resulting from incorrect user feedback (for example, supplying the wrong credentials at login) will continue to be reported with the same level of detail as before. These types of errors will not be logged. Additionally informational messages (as opposed to errors) will not be logged. As part of the system error logging feature, the Presentation Server 4.0 XML Service has been updated to replace many of the “unspecified” errors that it reports with a new “IMA error” which includes the hexadecimal error code reported by IMA. Web Interface contains a list of IMA error code to error message mappings which allows it to log the error description. The complete list of IMA Error codes is listed below.

6.2 Disable the default error message By default, server-side errors are suppressed by the .NET framework in order to avoid revealing any useful information to attackers. If any ASPX script contains an error, Web Interface will return the following generic error message:

65

Default error message: “An internal error occurred"

To determine the exact script and line number causing the problem, disable custom error reporting by disabling the customErrors element in <site-root>/web.config. Locate the following line in web.config: <customErrors mode="On" defaultRedirect="html/serverError.html" /> Change the mode to “Off”: <customErrors mode="Off" defaultRedirect="html/serverError.html" /> Then, save the file and reproduce the problem that was causing an error. Changes to web.config do not require a service restart. If the error was triggered by clicking an application icon, you will have to right-click the icon and select “Open in new window” in order to see the error report. The error report should now reveal much more detail, including which line from which script is causing the error:

Sample ASP.NET compilation error


66

Additional compiler information can be obtained by enabling the debug option in the web.config compilation tag: <compilation debug="true" defaultLanguage="C#"> After resolving the issue, be sure to restore web.config to its original state so that end users do not see detailed error messages.

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

To enable Tracing, edit the web.config file in the /Citrix/MetaFrame/ or <site-root> directory. Locate the following line:

<trace enabled="false" />

Change it to read as follows:

<trace enabled="true" pageOutput="true" localOnly="false" requestLimit="100" />

After saving changes, (no restart necessary), extended information will be written to the bottom of each page, including client cookies, session variables and HTTP Server Variables. You can also point your browser to <site-root>/Trace.axd and view a history of the last 100 requests. If you set pageoutput=“false” in web.config, trace information will not be appended to each page and you must browse to the Trace.axd page in order to view trace information. The trace.axd file does not actually exist, but the .NET framework returns information as though it did. For example:

67

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:


68

Trace detail excerpt

After obtaining the information you need from the trace, be sure to disable tracing again in web.config since it may reveal sensitive information to attackers:

<trace enabled="false" />

See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnaspnet/html/asp01252001.asp for more information about tracing in ASP.NET.

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

6.4.1 Try a simple ASPX file To confirm that ASP.NET core functionality is enabled, create a file called test.aspx with the following content: <%@ Page Language=C# %> <html> <body> The current time and date is: <% Response.Write(DateTime.Now.ToString()); %> </body> </html> Save the test.aspx file in the wwwroot directory and then point a browser to http://localhost/test.aspx. The output should reveal the current time. If you receive an error, then ASP.NET is failing and you should use Microsoft resources to troubleshoot the issue. Once you have the test.aspx script working, try the Web Interface URL again.

69

6.4.2 IIS ASP.NET Registration Sometimes convenient and sometimes troublesome, multiple versions of the .NET runtime may run side by side on the same machine. For example, if you have the .NET runtime 1.0 installed and then you install version 1.1, you now have both versions 1.0 and 1.1 available at the same time. So which runtime will be used by IIS? To answer this question Microsoft includes within the runtime a utility called aspnet_regiis.exe. This utility can report or alter the version of ASP.NET being used by IIS. The location of the .NET runtime is stored as a collection of metabase settings in IIS; and like all metabase settings it is possible to have multiple configurations vary according to virtual path. For example, you could have an ASP.NET application hosted at /MyApp which uses a different version of ASP.NET than the application /Citrix/MetaFrame. Web Interface requires .NET runtime version 1.1 or later, and the 1.1 runtime installer is included on the MetaFrame Presentation Server CD in the \Support folder (dotnetfx.exe). If IIS was not present when the runtime was installed, there may be no ASP.NET registration at all. This results in the default.aspx file being sent unparsed to the user when accessing the Web Interface URL:

Or if IIS is configured to use the .NET runtime version 1.0 instead of 1.1, you may see this: Server Error in '/Citrix/MetaFrame' Application. Configuration Error Description: An error occurred during the processing of a configuration file required to service this request. Please review the specific error details below and modify your configuration file appropriately. Parser Error Message: Unrecognized attribute 'validateRequest'. Source Error: Line 9: buffer="true" Line 10: enableViewState="false" Line 11: validateRequest="false" Line 12: /> Line 13: <globalization


70

Source File: D:\Inetpub\wwwroot\Citrix\MetaFrame\site\web.config Line: 11 Version Information: Microsoft .NET Framework Version:1.0.3705.0; ASP.NET Version:1.0.3705.0

To register IIS with version 1.1 of the framework, type: cd /d %systemroot%\Microsoft.net\Framework\v1.1.* aspnet_regiis –i

Aspnet_regiis.exe is installed at %SystemRoot%\Microsoft.net\Framework\Version. Full details on its usage are available in from the Microsoft TechNet Web site.

71

7. Reference Materials 7.1 Features not available on Web Interface for UNIX

Some features of Web Interface rely on core technologies provided by Microsoft Windows or Internet Information Services. These features are not available when Web Interface is running on UNIX Web servers or on Windows Web servers other than IIS.

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


72

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

Version Implementing Products Missing Web Interface 4.0 functionality

3.6.3 MetaFrame 1.8 NFuse 1.0

Smart Card Authentication Desktop Credentials Pass Through File type association SSL ICA connections NFuse Ticketing Group and folder based application acquisition

Change Password Workspace Control Zone Preference and Failover Integrated STA

3.6.4 MetaFrame 1.8 FR1 MetaFrame XP 1.0 XML Service for Unix 1.0 NFuse 1.5 NFuse 1.51

Smart Card Authentication Desktop Credentials Pass Through File type association SSL ICA connections Change Password Workspace Control Zone Preference and Failover Integrated STA

4.1 MetaFrame XP FR1 MetaFrame for Unix 1.1 FR1 NFuse 1.6 NFuse 1.61

Smart Card Authentication Desktop Credentials Pass Through File type association Change Password Workspace Control Zone Preference and Failover Integrated STA

4.2 MetaFrame XP FR2 MetaFrame XP FR3 NFuse Classic 1.7 NFuse Classic 1.71 Web Interface 2.0

Workspace Control Zone Preference and Failover Integrated STA

4.4 MetaFrame Presentation Server 3.0 Web Interface 3.0

Integrated STA Enhanced IMA Error Reporting

4.5 Presentation Server 4.0 Web Interface 4.0

None

73

7.3 IMA error codes relayed by the XML Service The XML Service is, for the most part, a Web service that wraps IMA operations for application enumeration and server resolution (among others) and allows them to be accessed over HTTP. When a client makes a request to the XML Service, the request is parsed into a suitable format and then sent on to IMA, which returns a response. The IMA response is then encoded into XML and sent back to the client. Prior to Presentation Server 4.0, the error handling mechanism in this component is such that when IMA returns an error, the XML responds to the caller like so:

If the IMA error is recognized by the XML Service, a <ResponseError> message is returned, containing an <ErrorId> value that represents the well-known error. Examples are: “failed-credentials” and “host-unreachable.”

<ResponseError> <ErrorId>host-unreachable</ErrorId> </ResponseError>

If the IMA error is not recognized by the XML Service, a <ResponseError> message

is returned, containing an <ErrorId> value of “unspecified.” In many circumstances, and additional <BrowserError> value is returned. If the IMA error is recognized as mapping to one of five browser error codes, then this value is set to the hexadecimal value of that code, otherwise it is set to 0x00000024 (BR_ERROR_IMA_UNKNOWN_ERROR).

<ResponseError> <ErrorId>unspecified</ErrorId> <BrowserError>0x00000024</BrowserError> </ResponseError>

The number of possible IMA error codes is of an order of magnitude higher than the number of defined browser codes, resulting in an ‘unspecified’ <ErrorId> and a <BrowserError> of 0x00000024 in the vast majority of failure modes, which is unsatisfactory when attempting to ascertain what went wrong and why.

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

The current IMA Error codes and their basic mnemonic descriptions are as follows:


74

IMA ID Source Facility ID Mnemonic

0x80000001 SYSTEM 0x0001 IMA_RESULT_UNKNOWN_FAILURE

0x80000002 SYSTEM 0x0002 IMA_RESULT_OUT_OF_MEMORY

0x80000003 SYSTEM 0x0003 IMA_RESULT_INVALID_ARG

0x80000004 SYSTEM 0x0004 IMA_RESULT_UNKNOWN_MESSAGE

0x80000005 SYSTEM 0x0005 IMA_RESULT_DESTINATION_UNREACHABLE

0x80000006 SYSTEM 0x0006 IMA_RESULT_REFERENCE_COUNT_NOT_ZERO

0x80000007 SYSTEM 0x0007 IMA_RESULT_ENTRY_NOT_FOUND

0x80000008 SYSTEM 0x0008 IMA_RESULT_NETWORK_FAILURE

0x80000009 SYSTEM 0x0009 IMA_RESULT_NOT_IMPLEMENTED

0x8000000A SYSTEM 0x000A IMA_RESULT_INVALID_MESSAGE

0x8000000B SYSTEM 0x000B IMA_RESULT_TIMEOUT

0x8000000C SYSTEM 0x000C IMA_RESULT_POINTER_IS_NULL

0x8000000D SYSTEM 0x000D IMA_RESULT_UNINITIALIZED

0x8000000E SYSTEM 0x000E IMA_RESULT_FINDITEM_FAILURE

0x8000000F SYSTEM 0x000F IMA_RESULT_CREATEPOOL_FAILURE

0x80000010 SYSTEM 0x0010 IMA_RESULT_SUBSYS_NOT_FOUND

0x80000014 SYSTEM 0x0014 IMA_RESULT_PS_UNINITIALIZED

0x80000015 SYSTEM 0x0015 IMA_RESULT_REGMAPFAIL

0x80000016 SYSTEM 0x0016 IMA_RESULT_DEST_TOO_SMALL

0x80000017 SYSTEM 0x0017 IMA_RESULT_ACCESS_DENIED

0x80000018 SYSTEM 0x0018 IMA_RESULT_NOT_SHUTTING_DOWN

0x80000019 SYSTEM 0x0019 IMA_RESULT_MUSTLOAD_FAILURE

0x8000001A SYSTEM 0x001A IMA_RESULT_CREATELOCK_FAILURE

0x8000001B SYSTEM 0x001B IMA_RESULT_SHUTDOWN_FAILURE

0x8000001C SYSTEM 0x001C IMA_RESULT_SENDWAIT_FAILURE

0x8000001D SYSTEM 0x001D IMA_RESULT_NO_COLLECTORS

0x8000001E SYSTEM 0x001E IMA_RESULT_UPDATED

0x8000001F SYSTEM 0x001F IMA_RESULT_NO_CHANGE

0x80000020 SYSTEM 0x0020 IMA_RESULT_LEGACY_NOT_ENABLED

0x80000021 SYSTEM 0x0021 IMA_RESULT_VALUE_ALREADY_CREATED

0x80000022 SYSTEM 0x0022 IMA_RESULT_UID_EXCEEDED_BOUNDS

0x80000023 SYSTEM 0x0023 IMA_RESULT_NO_EVENTS

0x80000024 SYSTEM 0x0024 IMA_RESULT_NOT_FOUND

0x80000025 SYSTEM 0x0025 IMA_RESULT_ALREADY_EXISTS

75


0x80000026 SYSTEM 0x0026 IMA_RESULT_GROUP_ALREADY_EXISTS

0x80000027 SYSTEM 0x0027 IMA_RESULT_NOT_A_GROUP

0x80000028 SYSTEM 0x0028 IMA_RESULT_GROUP_DIR_ACCESS_FAILURE

0x80000029 SYSTEM 0x0029 IMA_RESULT_EOF

0x8000002A SYSTEM 0x002A IMA_RESULT_REGISTRY_ERROR

0x8000002B SYSTEM 0x002B IMA_RESULT_DSN_OPEN_FAILURE

0x8000002C SYSTEM 0x002C IMA_RESULT_REMOVING_PSSERVER

0x8000002D SYSTEM 0x002D IMA_RESULT_NO_REPLY_SENT

0x8000002E SYSTEM 0x002E IMA_RESULT_PLUGIN_FAILED_VERIFY

0x8000002F SYSTEM 0x002F IMA_RESULT_FILE_NOT_FOUND

0x80000030 SYSTEM 0x0030 IMA_RESULT_PLUGIN_ENTRY_NOT_FOUND

0x80000031 SYSTEM 0x0031 IMA_RESULT_CLOSED

0x80000032 SYSTEM 0x0032 IMA_RESULT_PATH_NAME_TOO_LONG

0x80000033 SYSTEM 0x0033 IMA_RESULT_CREATEMESSAGEPORT_FAILED

0x80000034 SYSTEM 0x0034 IMA_RESULT_ALTADDRESS_NOT_DEFINED

0x80000035 SYSTEM 0x0035 IMA_RESULT_WOULD_BLOCK

0x80000036 SYSTEM 0x0036 IMA_RESULT_ALREADY_CLOSED

0x80000037 SYSTEM 0x0037 IMA_RESULT_TOO_BUSY

0x80000038 SYSTEM 0x0038 IMA_RESULT_HOST_SHUTTING_DOWN

0x80000039 SYSTEM 0x0039 IMA_RESULT_PORT_IN_USE

0x8000003A SYSTEM 0x003A IMA_RESULT_NOT_SUPPORTED

0x8000003B SYSTEM 0x003B IMA_RESULT_NOT_TRUSTED

0x80040001 DISTRIBUTION 0x0001 IMA_RESULT_MORE_ITEMS

0x80040002 DISTRIBUTION 0x0002 IMA_RESULT_SESSION_REQUEST_DENIED

0x80040003 DISTRIBUTION 0x0003 IMA_RESULT_JOB_NOT_FOUND

0x80040004 DISTRIBUTION 0x0004 IMA_RESULT_SESSION_NOT_FOUND

0x80040005 DISTRIBUTION 0x0005 IMA_RESULT_FILE_SEEK_FAILURE

0x80040006 DISTRIBUTION 0x0006 IMA_RESULT_FILE_READ_FAILURE

0x80040007 DISTRIBUTION 0x0007 IMA_RESULT_FILE_WRITE_FAILURE

0x80040008 DISTRIBUTION 0x0008 IMA_RESULT_JOB_CANNOT_BE_UPDATED

0x80040009 DISTRIBUTION 0x0009 IMA_RESULT_NO_TARGET_HOSTS

0x8004000A DISTRIBUTION 0x000A IMA_RESULT_NO_SOURCE_FILES

0x80130001 USER 0x0001 IMA_RESULT_MORE_ITEMS

0x80130002 USER 0x0002 IMA_RESULT_INVALID_ACCOUNT

0x80130003 USER 0x0003 IMA_RESULT_INVALID_PASSWORD

0x80130004 USER 0x0004 IMA_RESULT_EXPIRED_PASSWORD


76


0x80130005 USER 0x0005 IMA_RESULT_GROUP_IGNORED

0x80130006 USER 0x0006 IMA_RESULT_BUILTIN_GROUP

0x80130007 USER 0x0007 IMA_RESULT_DC_NOT_AVAILABLE

0x801300008 USER 0x0008 IMA_RESULT_NW_CLIENT_NOT_INSTALLED

0x80130009 USER 0x0009 IMA_RESULT_ACCOUNT_LOCKED_OUT

0x8013000A USER 0x000A IMA_RESULT_INVALID_LOGON_HOURS

0x8013000B USER 0x000B IMA_RESULT_ACCOUNT_DISABLED

0x8013000C USER 0x000C IMA_RESULT_PREFERRED_TREE_NOT_SET

0x8013000D USER 0x000D IMA_RESULT_EXPIRED_ACCOUNT

0x00130001 USER 0x0001 IMA_RESULT_ADSI_NOT_INSTALLED

0x00130002 USER 0x0002 IMA_RESULT_SECURITY_INFO_INCOMPLETE

0x80060001 DIRECTORY 0x0001 IMA_RESULT_ATTR_NOT_FOUND

0x80060002 DIRECTORY 0x0002 IMA_RESULT_CONTEXT_NOT_FOUND

0x80060003 DIRECTORY 0x0003 IMA_RESULT_VALUE_NOT_FOUND

0x80060004 DIRECTORY 0x0004 IMA_RESULT_DATA_NOT_FOUND

0x80060005 DIRECTORY 0x0005 IMA_RESULT_ENTRY_LOCKED

0x80060006 DIRECTORY 0x0006 IMA_RESULT_SEARCH_HASMORE

0x80060007 DIRECTORY 0x0007 IMA_RESULT_INCOMPLETE

0x80060008 DIRECTORY 0x0008 IMA_RESULT_READEXCEPTION

0x80060009 DIRECTORY 0x0009 IMA_RESULT_WRITEEXCEPTION

0x8006000A DIRECTORY 0x000A IMA_RESULT_LDAP_PARTIALINSTALL

0x8006000B DIRECTORY 0x000B IMA_RESULT_LDAP_NOTREADY

0x8006000C DIRECTORY 0x000C IMA_RESULT_BUFFER_TOO_SMALL

0x8006000D DIRECTORY 0x000D IMA_RESULT_CONTAINER_NOT_EMPTY

0x8006000E DIRECTORY 0x000E IMA_RESULT_CONFIGURATION_ERROR

0x8006000F DIRECTORY 0x000F IMA_RESULT_GET_BASEOBJECT

0x80060010 DIRECTORY 0x0010 IMA_RESULT_GET_DERIVEDOBJECT

0x80060011 DIRECTORY 0x0011 IMA_RESULT_OBJECTCLASS_NOTMATCH

0x80060012 DIRECTORY 0x0012 IMA_RESULT_ATTRIBUTE_NOTINDEXED

0x80060013 DIRECTORY 0x0013 IMA_RESULT_OBJECTCLASS_VIOLATION

0x8006014 DIRECTORY 0x0014 IMA_RESULT_ENUMFAIL

0x80060015 DIRECTORY 0x0015 IMA_RESULT_ENUMNODATA

0x80060016 DIRECTORY 0x0016 IMA_RESULT_DBCONNECT_FAILURE

0x80060017 DIRECTORY 0x0017 IMA_RESULT_TRUNCATE

0x80060018 DIRECTORY 0x0018 IMA_RESULT_DUPLICATE

0x80060019 DIRECTORY 0x0019 IMA_RESULT_PS_NOTINITIALIZED

77


0x8006001A DIRECTORY 0x001A IMA_RESULT_USING_ORACLE_7

0x8006001B DIRECTORY 0x001B IMA_RESULT_USING_ORACLE_8

0x8006001C DIRECTORY 0x001C IMA_RESULT_USING_ORACLE_UNKNOWN

0x8006001D DIRECTORY 0x001D IMA_RESULT_LOAD_DAO_ENGINE_FAILED

0x8006001E DIRECTORY 0x001E IMA_RESULT_COMPACT_DB_FAILED

0x80060033 DIRECTORY 0x0033 IMA_RESULT_ODBC_NO_CONNECTIONS_AVAILABLE

0x80060034 DIRECTORY 0x0034 IMA_RESULT_CREATE_SQL_ENVIRONMENT_FAILED

0x80060035 DIRECTORY 0x0035 IMA_RESULT_SQL_EXECUTE_FAILED

0x80060036 DIRECTORY 0x0036 IMA_RESULT_SQL_FETCH_FAILED

0x80060037 DIRECTORY 0x0037 IMA_RESULT_SQL_BIND_PARAM_FAILED

0x80060038 DIRECTORY 0x0038 IMA_RESULT_SQL_GET_COLUMN_DATA_FAILED

0x80060039 DIRECTORY 0x0039 IMA_RESULT_REPLICATED_DATA_CONTENTION

0x8006003A DIRECTORY 0x003A IMA_RESULT_DB_TABLE_NOT_FOUND

0x8006003B DIRECTORY 0x003B IMA_RESULT_CONNECTION_EXIST

0x8006003C DIRECTORY 0x003C IMA_RESULT_QUERY_MAX_NODEID_FAILED

0x8006003D DIRECTORY 0x003D IMA_RESULT_SQL_FUNCTION_SEQUENCE_ERROR

0x8006003E DIRECTORY 0x003E IMA_RESULT_DB_CONNECTION_TIMEOUT

0x8006003F DIRECTORY 0x003F IMA_RESULT_SQL_INVALID_TRANSACTION_STATE

0x80060040 DIRECTORY 0x0040 IMA_RESULT_DB_NO_DISK_SPACE

0x80060041 DIRECTORY 0x0041 IMA_RESULT_USING_ORACLE_9

0x80060042 DIRECTORY 0x0042 IMA_RESULT_TRANSACTION_ROLLEDBACK

0x002D 0000 RUNTIME 0x0001 IMA_RESULT_ALREADY_MASTER

0x802D0001 RUNTIME 0x0001 IMA_RESULT_TABLE_NOT_FOUND

0x802D0002 RUNTIME 0x0002 IMA_RESULT_NOT_TABLE_OWNER

0x802D0003 RUNTIME 0x0003 IMA_RESULT_INVALID_QUERY

0x802D0004 RUNTIME 0x0004 IMA_RESULT_TABLE_OWNER_HAS_CHANGED

0x802D0005 RUNTIME 0x0005 IMA_RESULT_SERVICE_NOT_AVAILABLE

0x802D0006 RUNTIME 0x0006 IMA_RESULT_ZONE_MASTER_UNKNOWN

0x802D0007 RUNTIME 0x0007 IMA_RESULT_NON_UNIQUE_HOSTID

0x802D0008 RUNTIME 0x0008 IMA_RESULT_REG_VALUE_NOT_FOUND

0x802D0009 RUNTIME 0x0009 IMA_RESULT_PARTIAL_LOAD

0x802D000A RUNTIME 0x000A IMA_RESULT_GATEWAY_NOT_ESTABLISHED

0x802D000B RUNTIME 0x000B IMA_RESULT_INVALID_GATEWAY

0x802D000C RUNTIME 0x000C IMA_RESULT_SERVER_NOT_AVAILABLE

0x80110104 LMS 0x0104 LMS_RESULT_NO_SERVER_AVAILABLE

0x80110200 LMS 0x0200 IMA_RESULT_FULL_SERVER_OR_APP_LOAD_REACHED


78


0x80260001 PRINTER 0x0001 IMA_RESULT_NW_PRINT_SERVER_ALREADY_PRESENT

0x80260002 PRINTER 0x0002 IMA_RESULT_SERVER_ALREADY_PRESENT

0x80300001 REMOTE_ACCESS 0x0001 IMA_RESULT_SERVICE_NOT_SUPPORTED

0x80300002 REMOTE_ACCESS 0x0002 IMA_RESULT_BUILD_SD_FAILED

0x80300003 REMOTE_ACCESS 0x0003 IMA_RESULT_RPC_USE_ENDPOINT_FAILED

0x80300004 REMOTE_ACCESS 0x0004 IMA_RESULT_RPC_REG_INTERFACE_FAILED

0x80300005 REMOTE_ACCESS 0x0005 IMA_RESULT_RPC_LISTEN_FAILED

0x80300006 REMOTE_ACCESS 0x0006 IMA_RESULT_BUILD_FILTER_FAILED

0x80300007 REMOTE_ACCESS 0x0007 IMA_RESULT_RPC_BUFFER_TOO_SMALL

0x80300008 REMOTE_ACCESS 0x0008 IMA_RESULT_REQUEST_TICKET_FAILED

0x80300009 REMOTE_ACCESS 0x0009 IMA_RESULT_INVALID_TICKET

0x8030000A REMOTE_ACCESS 0x000A IMA_RESULT_LOAD_TICKETDLL_FAILED

79

7.4 HTTP Server Environment Variables This table, taken from MSDN, lists the HTTP Server environment variables available in IIS. These variables are accessible through the Request.ServerVariables collection, e.g.: Your client IP is <%=Request.ServerVariables["REMOTE_ADDR"] %>

Variable Description

ALL_HTTP All HTTP headers sent by the client.

ALL_RAW Retrieves all headers in raw form. The difference between ALL_RAW and ALL_HTTP is that ALL_HTTP places an HTTP_ prefix before the header name and the header name is always capitalized. In ALL_RAW the header name and values appear as they are sent by the client.

APPL_MD_PATH Retrieves the metabase path for the Application for the ISAPI DLL.

APPL_PHYSICAL_PATH Retrieves the physical path corresponding to the metabase path. IIS converts the APPL_MD_PATH to the physical (directory) path to return this value.

AUTH_PASSWORD The value entered in the client's authentication dialog. This variable is available only if Basic authentication is used.

AUTH_TYPE The authentication method that the server uses to validate users when they attempt to access a protected script.

AUTH_USER The name of the user as it is derived from the authorization header sent by the client, before the user name is mapped to a Windows account. This variable is no different from REMOTE_USER. If you have an authentication filter installed on your Web server that maps incoming users to accounts, use LOGON_USER to view the mapped user name.

CERT_COOKIE Unique ID for client certificate, returned as a string. Can be used as a signature for the whole client certificate.

CERT_FLAGS bit0 is set to 1 if the client certificate is present. bit1 is set to 1 if the Certification authority of the client certificate is invalid (it is not in the list of recognized CAs on the server).

CERT_ISSUER Issuer field of the client certificate (O=MS, OU=IAS, CN=user name, C=USA).

CERT_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For example, 128.

CERT_SECRETKEYSIZE Number of bits in server certificate private key. For example, 1024.

CERT_SERIALNUMBER Serial number field of the client certificate.

CERT_SERVER_ISSUER Issuer field of the server certificate.

CERT_SERVER_SUBJECT Subject field of the server certificate.

CERT_SUBJECT Subject field of the client certificate.

CONTENT_LENGTH The length of the content as given by the client.

CONTENT_TYPE The data type of the content. Used with queries that have attached information, such as the HTTP queries GET, POST, and PUT.


80


GATEWAY_INTERFACE The revision of the CGI specification used by the server. The format is CGI/revision.

HTTP_<HeaderName> The value stored in the header HeaderName. Any header other than those listed in this table must be prefixed by HTTP_ in order for the ServerVariables collection to retrieve its value. Note The server interprets any underscore (_) characters in HeaderName as dashes in the actual header. For example if you specify HTTP_MY_HEADER, the server searches for a header sent as MY-HEADER.

HTTP_ACCEPT Returns the value of the Accept header.

HTTP_ACCEPT_LANGUAGE Returns a string describing the language to use for displaying content.

HTTP_COOKIE Returns the cookie string that was included with the request.

HTTP_HOST Returns the name of the Web server. This may or may not be the same as SERVER_NAME depending on type of name resolution you are using on your Web server (IP address, host header).

HTTP_REFERER Returns a string that contains the URL of the page that referred the request to the current page using an HTML <A> tag. Note that the URL is the one that the user typed into the browser address bar, which may not include the name of a default document. If the page is redirected, HTTP_REFERER is empty. HTTP_REFERER is not a mandatory member of the HTTP specification.

HTTP_USER_AGENT Returns a string describing the browser that sent the request.

HTTPS Returns ON if the request came in through secure channel (SSL) or it returns OFF if the request is for a non-secure channel.

HTTPS_KEYSIZE Number of bits in Secure Sockets Layer connection key size. For example, 128.

HTTPS_SECRETKEYSIZE Number of bits in server certificate private key. For example, 1024.

HTTPS_SERVER_ISSUER Issuer field of the server certificate.

HTTPS_SERVER_SUBJECT Subject field of the server certificate.

INSTANCE_ID The ID for the IIS instance in textual format. If the instance ID is 1, it appears as a string. You can use this variable to retrieve the ID of the Web-server instance (in the metabase) to which the request belongs.

INSTANCE_META_PATH The metabase path for the instance of IIS that responds to the request.

LOCAL_ADDR Returns the Server Address on which the request came in. This is important on multi-homed computers where there can be multiple IP addresses bound to the computer and you want to find out which address the request used.

81


LOGON_USER The Windows account that the user is impersonating while connected to your Web server. Use REMOTE_USER or AUTH_USER to view the raw user name that is contained in the request header. The only time LOGON_USER holds a different value than these other variables is if you have an authentication filter installed.

PATH_INFO Extra path information as given by the client. You can access scripts by using their virtual path and the PATH_INFO server variable. If this information comes from a URL, it is decoded by the server before it is passed to the CGI script.

PATH_TRANSLATED A translated version of PATH_INFO that takes the path and performs any necessary virtual-to-physical mapping.

QUERY_STRING Query information stored in the string following the question mark (?) in the HTTP request.

REMOTE_ADDR The IP address of the remote host making the request.

REMOTE_HOST The name of the host making the request. If the server does not have this information, it will set REMOTE_ADDR and leave this empty.

REMOTE_USER The name of the user as it is derived from the authorization header sent by the client, before the user name is mapped to a Windows account. If you have an authentication filter installed on your Web server that maps incoming users to accounts, use LOGON_USER to view the mapped user name.

REQUEST_METHOD The method used to make the request. For HTTP, this is GET, HEAD, POST, and so on.

SCRIPT_NAME A virtual path to the script being executed. This is used for self-referencing URLs.

SERVER_NAME The server's host name, DNS alias, or IP address as it would appear in self-referencing URLs.

SERVER_PORT The port number to which the request was sent.

SERVER_PORT_SECURE A string that contains either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.

SERVER_PROTOCOL The name and revision of the request information protocol. The format is protocol/revision.

SERVER_SOFTWARE The name and version of the server software that answers the request and runs the gateway. The format is name/version.

URL Gives the base portion of the URL.


82

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>

WI4 Troubleshooters Guide

Documents

Transcript of WI4 Troubleshooters Guide