Professional Documents
Culture Documents
0
Troubleshooters Guide
Table of Contents
About this document ..........................................................................................3 1. Whats 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 Whats installed ...................................................................................7 3.2.2 Whats 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
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
on the Web server. NDS authentication is still unavailable on Web Interface for UNIX.
2. Platform support
2.1 Supported Server Platforms
Tier 1 Mainstream platforms, fully tested O/S Windows Server 2003 with or without SP1 Windows 2000 SP4+ Red Hat Enterprise Edition O/S Solaris 9 Red Hat Enterprise Edition Solaris 9 Red Hat Enterprise Edition Hardware x86 x86 x86 Hardware Sparc x86 Sparc x86 Web server IIS 6.0 IIS 5.0 Apache 2.x Web server SunOne 8 Apache 1.3 WebLogic Server 8.x WebSphere Application Server 5.x CLR/JDK .Net/J# 1.1 .Net/J# 1.1 Sun 1.4.x JDK Sun 1.4.x Sun 1.4.x WebLogic WebSphere JSP N/A N/A Tomcat 5.x JSP SunOne Tomcat 5.x WebLogic WebSphere
Other metabase modifications made by the site manager tool include the following: IIS is configured to parse .ica files using aspnet_isapi.dll
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 sites default document list
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 commandline options detailed for WebInterfaceSetup.exe below EXCEPT -noasc, q, -e, and -p. If necessary, the zip file extraction step may be skipped and command-line options can be passed to the self-extractor via an environment variable. The self-extractor cannot accept command line arguments directly. Set the environment variable WI_COMMAND_LINE equal to the command line you wish to use, and then invoke the self-extractor with no arguments. When using this option, use the \ character to escape spaces within arguments. If the \ character is needed to express a directory path, use \\ instead. For example:
C:\>set WI_COMMAND_LINE=-q -noasc -g c:\\wi\\logfile -c WIDest=1:/Citrix/MetaFrame,Config=Local,XMLService=mfpsrv01:80;mfpsrv02:8 0,WIDefaultSite=Yes C:\>WebInterface.exe
-p <path>
Installs site management tool and language packs to <path>. This option implies a silent installation of Web Interface. Installs Web Interface silently. Installs a new site defined by <sitedef>, which is a comma separated list of <arg>=<value> pairs. See the next table for a specification. 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.
-q -c <sitedef>
-e <path>
-g <logpath> -h or -?
Log the operation(s) performed and save the log files in <logpath>. Displays the programs version and a summary of the accepted command line options, then quits. All other command line options are ignored. Prints out a summary of all sites currently installed on the machine. This option can only be specified by itself. 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). Modifies an existing site specified by <sitedef>. Removes an existing site specified by <sitedef>. Uninstalls the Web Interface. This option can only be specified by itself.
-i
No summary is shown.
-l <language>
If no other command line options are supplied, the user is prompted to select a language for the installation program.
-m <sitedef> -r <sitedef> -u
Existing sites are not modified. No site is removed. Web Interface is not uninstalled.
10
Site beneath /Citrix/MetaFrame, using a local configuration file with the server MPS401 providing the Citrix XML Service:
"WIDest=1:/Citrix/MetaFrame,Config=Local,XMLService=MPS401:8080"
Options which may be included in a site definition string are defined in the following table. All options and values are case-sensitive.
Option WIDest=<IISSite>:<path> Meaning 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 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 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 Modify/remove the Web Interface site at path <path> under IIS site <IISSite> (the number of the IIS site). Modify/remove the Program Neighborhood Agent site at path <path> under IIS site <IISSite> (the number of the IIS site). Modify/remove the MetaFrame Conferencing Manager site at path <path> under IIS site <IISSite> (the number of the IIS site). 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 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. Configures the initial farm to have name <farm_name>. If configuration source is not local, an error occurs. If absent, Farm1 is used. 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. 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. 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.
PNADest=<IISSite>:<path>
MCMDest=<IISSite>:<path>
WICurrent=<IISSite>:<path> PNACurrent=<IISSite>:<path>
MCMCurrent=<IISSite>:<path>
WIDefaultSite=Yes|No
FarmName=<farm_name>
XMLService=<server>:<port>
XMLSProtocol=HTTP|HTTPS|SSL
XMLSSSLPort=<port>
11
Option ECS=<server>:<port>
Meaning 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. 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. 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. 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. 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.
ECSSecure=Yes|No
WIApplyChangesURL=<URL>
PNAApplyChangesURL=<URL>
MCMApplyChangesURL=<URL>
Example 2 Add a site that uses remote configuration This command adds two new sites to an existing Web Interface 4.0 server. The new sites will use the XML services MPS401:8080 and MPS402:8080 as configuration sources as well as the sources for published application information. We have created a new site in IIS that we wish to use to serve the Web Interface sites. The new IIS site has an identifier of 894881:
12
We wish to install the Web Interface and Program Neighborhood Agent Services sites on this new IIS Web site.
cd "program files\citrix\web interface\4.0" sitemgr.exe c "WIDest=894881:/Citrix/MetaFrame,PNADest=894881:/Citrix/PNAgent,XMLService =MPS401:8080;MPS401:8080,Config=MPS401:8080;MPS402:8080"
Example 3 Move Web Interface from the Default Web Site to a new site The following command moves a Web Interface 4.0 site from the Default Web Site to the site whose identifier is 894881:
cd "program files\citrix\web interface\4.0" sitemgr.exe m "WICurrent=1:/Citrix/MetaFrame,WIDest=894881:/Citrix/MetaFrame"
13
Option XMLService=<server>:<port>
Meaning 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. 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. 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. 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. 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.
XMLSProtocol=HTTP|HTTPS|SSL
XMLSSSLPort=<port>
ECS=<server>:<port>
ECSSecure=Yes|No
14
Web Interface 4.0 Remote Configuration design The Configuration Manager runs on Presentation Server 4.0 as a DCOM application. It is always installed with Presentation Server 4.0 but only initiates when a request for its services is received. By default, it runs in the process ConfigMgrSvr.exe under the security context of a local account called Ctx_ConfigMgr. If necessary, this identity can be edited using the Component Services snap-in (dcomcnfg.exe):
Web Interface site configurations are submitted to the configuration manager by the Access Suite Console, which loads a .NET assembly called the Configuration Object Library (COL) for these purposes. In order to use a Configuration Manager, the user running the Access Suite Console must be authenticated as a Presentation Server administrator who has been granted the delegated administration privilege called Log on to Web Interface Console in the MetaFrame Presentation Server Console:
15
The Configuration Manager interacts with the IMA Service to store configuration files as binary blobs in the IMA database. On startup or after any change has been made to a central configuration file, Web Interface downloads its configuration using the Configuration Proxy. The configuration proxy is similar to the Secure Ticket Authority: it is an ISAPI plug-in that provides a readonly 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.
16
<ComponentRegInfo key="Technology">ASPX</ComponentRegInfo> <ComponentRegInfo key="PlatformOS">Windows Server 2003</ComponentRegInfo> <ComponentRegInfo key="UpdateURL">http://wisrv/MPS/reloadConfiguration.aspx</ComponentRegInfo> </RequestRegistration> </ConfigProtocol>
If the configuration proxy responds with a message saying the site ID is not recognized, then Web Interface posts an XML request that registers the site with the configuration manager. The user will receive an error stating that no configuration is available:
Once the site is registered, a default configuration is created and the site can be edited using the Access Suite Console. For Windows Web servers, the Create site task in the Access Suite Console simultaneously unpacks the site files into the appropriate location and registers the site with the configuration manager if remote configuration is chosen. But for UNIX Web servers, the registration process must take place after the site has been created. Therefore the first request to a new JSP site using remote configuration will always fail. After the first request, the site will have been registered with the configuration manager and the administrator can use the Access Suite Console from any Windows machine to edit the configuration of the JSP site.
17
Note that if the sharutils package is not installed, the installation will fail with the following error, citing the absence of uudecode:
./WebInterface.sh: line 175698: uudecode: command not found tar: WebInterface.tar: Cannot open: No such file or directory tar: Error is not recoverable: exiting now ./WebInterface.sh: line 175716: cd: /tmp/WebInterface/WebInterface: No such file or directory Exception in thread "main" java.lang.NoClassDefFoundError: com/citrix/wi/install/UnixSiteTool
To install the sharutils package, type yum install sharutils or up2date sharutils. If sharutils is present, setup begins.
Web Interface for MetaFrame Presentation Server Setup
18
This utility prepares the Web Interface for use. at any time to quit. <Press Enter to view the License Agreement>
19
edit the weblogic.xml within the WEB-INF directory of this WAR file.
At this point, a new MetaFrame.war file and corresponding tomcat XML file has been created in the current directory:
# ls -l total 12776 -rw-r--r-- 1 root root 665 Apr -rw-r--r-- 1 root root 2150903 Apr -rwxr-xr-x 1 root root 10887457 Apr
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/
At this point the Web application should be loaded. Point a browser to http://tomcatserver/Citrix/MetaFrame/. By default, Tomcat listens on port 8080, so the URL will be similar to this: http://192.168.0.117:8080/Citrix/MetaFrame/ On the first load, you will receive the following error message, stating that the system configuration is invalid or unavailable:
20
After this error is shown, the site should be registered with your Presentation Server 4.0 Configuration Manager. Move to a Windows workstation and launch the Access Suite Console. Configure and run discovery, being sure to list the correct Presentation Server as a Web Interface Configuration Server. Your Web Interface for UNIX site should now appear in the Access Suite Console:
From this point on, you can use the Access Suite Console to manage all the settings for the Web Interface for UNIX site.
21
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.
22
To remove a language from the list, simply delete or rename its corresponding .lang file and then restart the Web service. The collection of static strings is defined in several resource files. For English, the files are: common_strings.properties Strings common to all site types metaframe_strings.properties Strings used for MetaFrame Presentation Server sites mcmguest_strings.properties Strings used for MetaFrame Conferencing Manager sites mpssourceimpl_strings.properties Error messages related to MetaFrame Presentation Server site functionality pnagent_strings.properties Error messages related to Program Neighborhood Agent site functionality pnagentimpl_strings.properties More error messages related to Program Neighborhood Agent site functionality SslErrorMessages.properties Error messages for the SSL SDK webpnimpl_strings.properties Error messages regarding the internal WebPN object xmlclient_strings.properties Error messages related to communications with the Citrix XML Service and Secure Ticket Authority This collection of properties files constitutes the English language pack for Web Interface. Additional language packs contain the same set of files, but with the language code appended to the file name. For example, the German language pack files are common_strings_de.properties, metaframe_strings_de.properties, etc. Each MetaFrame Presentation Server site includes its own languages folder, which is initially empty. To add a language pack that should be used only for one site, add it to the sites languages folder instead of the languages folder beneath Program Files\Citrix\Web Interface. The resource files contain static strings, each with a key value assigned. Keys are defined for all visible words (other than application names), including the welcome message, tool tips, client installation captions, and error messages. Here are a few examples:
LoginTitle=MetaFrame Presentation Server Login PleaseLogin=Please log in PINRejected=Your PIN could not be set. SettingsError2=Please enter a valid window size.
In the scripts, strings are displayed by calling the getString() function with the current locale. For example, the following ASP code would display the text Your PIN could not be set.:
<%= getString("PINRejected", currentLocale) %>
New keys and strings can be added to the resource files if desired. However, simply editing the files with Notepad is not sufficient. The properties files can only be modified by an editor which recognizes the format of Java Properties Files. If you have an editor available that can directly modify Java Properties files, you can use that tool to modify the files. Otherwise, you'll need to follow the instructions below to modify the files in a conventional text editor.
23
The first step is to convert the Properties files into text files. To do this you need to use the native2ascii tool available from java.sun.com as part of the J2SE Software Development Kit, for example:
%JAVA_HOME%\bin\native2ascii -reverse -encoding UTF8 common_strings.properties common_strings.txt
You can then edit the .txt in a UTF-8 aware text editor. Notepad is capable of this task. When you have finished modifying a file, you must convert it back into a properties file using the native2ascii tool, for example:
%JAVA_HOME%\bin\native2ascii -encoding UTF8 common_strings_it_IT.txt common_strings.properties
After making changes to the properties file, restart the Web server service in order to make the changes effective.
It is also possible to configure Web Interface 4.0 with NDS credentials to make an authenticated bind to the Novell server. To do this, locate the customization point within the file loginNDS.cs:
// CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP // // CUSTOMIZATION POINT // // Set ndsAdminUsername and ndsAdminPassword to "" to use anonymous bind // For non-anonymous binds SSL must be used so ensure the following: // - the NDS ceritificate must be in the trusted part of the local // machine's certificate store (use mmc) // - the NDS server name must match the certificate ie. be fully qualified // // CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP CP string ndsAdminUsername = ""; //"cn=Administrator,ou=company,o=com"; string ndsAdminPassword = ""; //"password";
Note that the connection is made over SSL if you supply a password as eDirectory requires this by default. There are three ways of logging in to Web Interface using NDS credentials: 1. Fully qualified user name For example, .user.company.com. The selection in the context drop down has no effect. The user will be authenticated in the context given as part of the fully qualified user name.
24
2. Non qualified user name with context selected For example, user and company.com selected in drop down. The user will be authenticated in the chosen context. 3. Non qualified user name with Find context selected This is the only case where the new context search functionality is used. The entire directory is searched for a user with the given name. If no matching user is found, an error message to that effect is displayed. If exactly one user is found, the authentication is performed against that particular user in that context. If multiple users are found in different contexts, the login page is shown again with the contexts of the users discovered added to the contents of the context drop down. In this case, the user must enter their user name and password again and select one of the contexts to authenticate. No matter which method is used to select a user name and context, if the configured context list is not empty, the chosen context must be in the configured list otherwise the login is not permitted.
RSA integrated logon The RSA passcode consists of a secret PIN code that the user knows, followed by the 6digit 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 users PIN and token code are correct for the given time of day. 25
RSA SecurID 6.0 introduces a new feature that allows users to log in using the RSA passcode only. The domain password is managed and provided by the RSA serverusers are not required to know or enter their domain password. Web Interface 4.0 supports RSA 6.0 password integration. To enable this feature, select the Use Windows password integration checkbox on the Explicit authentication settings dialog in the Access Suite Console:
Enabling RSA SecurID 6.0 password integration With this feature enabled, users are prompted to enter only their user name and passcode on the Web Interface login page:
26
How it works
The Web Interface server scripts responsible for user authentication include functions to validate an RSA passcode. RSA 6.0 with Windows password integration follows this process:
RSA SecurID 6.0 Integrated Password Authentication 1. Client accesses the Web Interface server and is prompted for their user name and passcode. 2. Web Interface calls on code in <site-root>/auth/bin/Authenticators.dll to instantiate an RSA client object and authenticate the users 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 users domain password back to Web Interface. 3. Web Interface receives the users domain password from the RSA 6.0 server and sends it to the XML Broker. The explicit authentication process follows normally from there.
27
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 users password from the POST request will be visible on the network:
POST /Citrix/MetaFrame/default/login.aspx HTTP/1.1 Content-Type: application/x-www-form-urlencoded User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; .NET CLR 1.1.4322) state=LOGIN&LoginType=Explicit&user=jayt&password=secret&domain=TOMLIN&log in=Log+In
Upon receiving the users credentials from the HTTP POST, Web Interface translates them into an XML request and sends them to the XML Broker as part of the application enumeration request:
28
<NFuseProtocol version="4.2"> <RequestAppData> <Scope traverse="onelevel"></Scope> <DesiredDetails>defaults</DesiredDetails> <DesiredDetails>file-type</DesiredDetails> <ServerType>all</ServerType> <ClientType>ica30</ClientType> <ClientType>content</ClientType> <Credentials> <UserName>jayt</UserName> <Password encoding="ctx1">MPGKPGFDILDOPOFLIMCJLPBK</Password> <Domain type="NT">TOMLIN</Domain> </Credentials> <ClientName>WI_1gykQ6/J7yKTj1ooSxKn</ClientName> <ClientAddress addresstype="dot">192.168.0.152</ClientAddress> </RequestAppData> </NFuseProtocol>
This traffic may be secured using SSL Relay, but note that the password is no longer in clear text here; it is scrambled, but this is not considered strong encryption. Before the XML Broker returns applications for the user, the credentials must be validated. This task is delegated to the IMA Service, which in turn calls LogonUser() and LookupAccoutSid() from the local security account subsystem in Windows (LSASS.EXE).
Explicit user authentication 1. User sends credentials to Web Interface via HTTP POST command. 2. Web Interface includes credentials as part of the application enumeration request. 3. The XML Service delegates user authentication and application enumeration to the local IMA Service, which ultimately makes calls to the local security authority (LSASS).
Novell integration
When integrating with Novell NDS, Web Interface attempts to perform contextless logins by locating the user object within the NDS tree. For this action to succeed, the Web Interface server must be able to contact a Novell NDS server on TCP port 389 (LDAP). By
29
default, Web Interface searches the entire tree until it finds a user object matching the current user name. To restrict this search to a limited number of contexts, enter the contexts into the Access Suite Console. For more information about integrating with Novell NDS, see article CTX101898. The article was written for MetaFrame XP Feature Release 2 and NFuse Classic 1.7, but the Novell integration features in Web Interface have not changed since then.
How it breaks
Policy settings at the XML Broker prevent logon Because the user authentication task is deferred to the local operating system at the XML Broker, explicit logins should work as long as the user is able to log on locally at the XML Broker server. To confirm this, make an ICA or RDP connection directly to the XML Broker desktop and attempt to log on using the standard Windows GINA. Any problems that occur using the standard GINA, such as issues with custom redirectors or the inability to locate a domain controller, will similarly affect Web Interface authentication. However, keep the following in mind when testing logins at the XML Broker: Enumerating farm icons with the Program Neighborhood client from the Web Interface server is not a valid test of the users 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.
30
an application does. If the XML Broker is not a ZDC, application address requests are forwarded to the data collector of the zone in which the XML Broker resides. Can an XML Broker that belongs to Domain A authenticate a user from Domain B? Yes, as long as Domain A trusts Domain B. This is no different from logging in through the standard Windows GINA as discussed above. Users are being forced to reauthenticate every 20 minutes. How do I change this session timeout? Because the session is controlled by the .NET runtime instead of IIS, changing the session timeout value in Internet Services Manager as discussed in CTX191516 does not affect Web Interface 3.0. Instead, you should add a sessionState element to the <system.web> section of web.config declaring a new timeout in minutes. For example, to change the session timeout to one hour, add the following line to /Citrix/MetaFrame/site/web.config:
<configuration> <system.web> <sessionState timeout="60" /> <compilation debug="false" defaultLanguage="C#"> <assemblies>
Note: Web.config entries are case sensitive and take effect immediately. Use sessionState, not sessionstate.
How it works
1. The user begins by accessing the default URL for Web Interface. 2. Web Interface triggers an Integrated Windows Authentication challenge/response handshake between the Web browser and IIS. 3. After a successful Integrated Windows authentication, IIS impersonates the authenticated user to produce a list of domain groups to which the user belongs. The AUTH_USER server variable will be populated with the authenticated domain name and user name (for example, AUTH_USER=TOMLIN\jayt). 4. Web Interface uses this information to enumerate applications.
How it breaks
Restricted NTFS permissions After successfully negotiating Integrated Windows Authentication, IIS impersonates the current user account when accessing files on the Web servers hard drive. Compare this to anonymous authentication, where IIS impersonates the IUSR account in order to access local resources. This design mandates that the users domain account have at least Read permission on all scripts beneath the Web servers document root directory. Therefore, administrators who restrict NTFS permissions on the files beneath wwwroot to allow access only by Administrators or the IUSR account will find that non-administrator users are unable to view Web Interface pages.
31
To correct this problem, ensure that in addition to the IUSR account, all users who will access the Web Interface have NTFS read permissions on all files beneath wwwroot/Citrix on the Web server. Proxy servers disrupt Integrated Windows authentication If you attempt to access the Web Interface via an HTTP proxy server, the NTLM challenge/response authentication required for single sign on will likely fail. Integrated Windows authentication is generally not possible through proxy servers, including the case where HTTPS traffic is proxied through Secure Gateway en route to Web Interface. See the Microsoft TechNet Web site for details. To resolve this issue, bypass the proxy server or use HTTPS to the IIS SSL port.
How it works
A user is provided with a smart card reader and is issued a smart card containing a user certificate and private key. In order to access the private key stored on the smart card, the user must provide their PIN code, usually a 4-digit number. Any Web site or virtual directory served by IIS can be configured to accept or require client certificates:
32
Configuring IIS to require client certificates The Web Interface installer applies these metabase settings when smart card authentication is enabled. Once the client certificate has been validated and sent to IIS, the Web server communicates with an Active Directory domain controller to map the certificate to a domain user account. As outlined in the Web Interface Administrators Guide, this step requires that the Windows directory service mapper be enabled on the WWW Service Master Properties dialog in Internet Services Manager:
33
Enable the Windows directory service mapper By default, this feature is not enabled in IIS. Once a successful account mapping has been made, the domain controller returns a token for the identified user and IIS impersonates the users domain account for script access. More information about client certificate mapping in IIS is available from the Microsft TechNet Web site.
How it breaks
IIS is misconfigured If the metabase settings on the certificate virtual directory are modified so that client certificates are no longer required or client certificate mapping is not enabled, Web Interface cannot authenticate the user. To correct this problem, use the Repair option for the site in the Access Suite Console.
34
How it works
The task of changing a users password is deferred to the XML Service running on Presentation Server. This relieves the Web server from needing any ties to the users 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 35
ChangePassword() method is used for UPN user names. Therefore the XML Broker must have connectivity to a domain controller.
How it breaks
If for any reason a user is not able to change their password from the Windows GINA on the MetaFrame XML Broker, then Web Interface password changes will fail. If the XML Service is being hosted by IIS, then the file Inetpub\Scripts\ctxadmin\ctxadmin.dll must be present and must be served anonymously (same as wpnbr.dll).
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>
36
<Password encoding="ctx1">NFHALEBBMHGCMAJNOHLLKBP</Password> <Domain type="NT">READINESS</Domain> </Credentials> <ClientName>WI_Ucs/237RBAKqj9tf</ClientName> <ClientAddress addresstype="dot">192.168.0.152</ClientAddress> </RequestAppData> </NFuseProtocol>
2. To determine the users application set, the XML Broker queries its local host cache of the IMA database. (Application launch requests require communication with a zone data collector; application enumeration requests do not.) 3. The XML Service responds with a <ResponseAppData> document detailing information about each application to which the user has access:
<NFuseProtocol version="4.1"> <ResponseAppData> <AppDataSet> <Scope traverse="onelevel"/> <AppData> <InName>Access</InName> <FName>Access</FName> <Details> <Settings appisdisabled="false" appisdesktop="false"> <Folder>Office XP</Folder> <Description/> <WinWidth>640</WinWidth> <WinHeight>480</WinHeight> <WinColor>2</WinColor> <WinType>pixels</WinType> <WinScale>75</WinScale> <SoundType minimum="false">basic</SoundType> <VideoType minimum="false">none</VideoType> <Encryption minimum="false">basic</Encryption> <AppOnDesktop value="false"/> <AppInStartmenu value="false"/> <PublisherName>readiness</PublisherName> <SSLEnabled>false</SSLEnabled> <RemoteAccessEnabled>true</RemoteAccessEnabled> </Settings> </Details> <SeqNo>1070633217</SeqNo> <ServerType>win32</ServerType> <ClientType>ica30</ClientType> </AppData> <AppData> (AppData section repeated for each application) </AppData> </AppDataSet> </ResponseAppData> </NFuseProtocol>
Notice the <SeqNo> element within the AppData response. This sequence number is updated each time a change is made to the published application. If Web Interface has not yet retrieved the icon graphic for a published application, it will request the icon with another <RequestAppData> command:
<NFuseProtocol version="4.2"> <RequestAppData> <Scope traverse="onelevel"></Scope> <DesiredDetails>icon</DesiredDetails> <AppName>Access</AppName>
37
<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
38
results from corruption of the IMA local host cache on the XML Broker server. See article CTX759510 for instructions on how to refresh or recreate the local host cache.
39
2. The XML Service queries IMA to obtain the list of applications that have been published to the user or any of the groups in the list. Note that the XML Broker does not perform user authentication at this point, as the users 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
40
limit. See CTX943036 for information about hotfixes and a registry flag that can be set to increase the maximum XML request size.
How it works
When a user clicks an application icon, Web Interface sends a request to the XML Broker asking for the address of a target MetaFrame server to which the user should connect. Web Interface will ask for the normal or the alternate server address depending on which addressing method has been determined for the current client IP. For example:
<RequestAddress> <Name> <AppName>Microsoft Outlook</AppName> </Name> <ClientName>WI_Ucs/237RBAKqj9tf</ClientName> <ClientAddress addresstype="dot">192.168.0.152</ClientAddress> <ServerAddress addresstype="dot-port"></ServerAddress> <Credentials> <UserName>jayt</UserName> <Password encoding="ctx1">NFHALE...MAJNOHLLKBP</Password> <Domain type="NT">readiness</Domain> </Credentials> <ClientType>ica30</ClientType> <ClientCookie name="ServerPreferenceInfo">ABA...ACM</ClientCookie> </RequestAddress>
The XML Broker queries the nearest zone data collector (ZDC) to retrieve a target server address. The ZDC checks for several conditions: 1. If the user has a disconnected session running the current application, the ZDC will ignore load levels and return the address of the server where the disconnected session resides. 2. If any MetaFrame policies have been defined with zone preference information, the zone preferences are taken into consideration. Zone preference is ignored when reconnecting users to a disconnected session and zone preference can never prevent a user from being connected. For example, if the user is affected by a MetaFrame policy which sets a Do not connect preference for Zone 3 but the user has a disconnected session on a server in zone 3, the user will still get reconnected to their session in spite of the zone preference policy. 3. If any Load Evaluators are attached to the current application, they are used to determine the least busy server within the farm or preferred zone. 4. Once an appropriate target server has been identified, the ZDC sends it an IMA ping to ensure that it is alive before returning its address to the XML Broker. 5. If the target server has multiple IP addresses, the ZDC attempts to determine which IP address would be appropriate for the current client IP.
41
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
42
Wrong address returned for servers with more than one network card In each IMA zone, the zone data collector (ZDC) is responsible for resolving application load balancing requests by returning the IP address of the least busy presentation server for any given application name. When the least-busy server contains multiple network interface cards (NICs) with IP addresses on different subnets, a determination must be made about which address to return. To make this determination, the ZDC uses the following process: 1. The ZDC obtains the client IP address from the incoming request. For Web Interface users, this address will be the value of REMOTE_ADDR or the address of the Web server if Secure Gateway and Web Interface are collocated. 2. If the ZDC has multiple network cards, it uses its own routing table to determine which of its interfaces would be used to route traffic to the client IP address. 3. The address of the target server which most closely matches the result of the previous step is chosen and returned to the client. This process usually works fine when all servers in the farm have interfaces on the same networks, but the wrong address could be chosen under the following circumstances: ZDC has only one interface - When the ZDC has only one NIC but member servers have multiple NICs, then the result of step 2 above is always the same and addresses from only one network are ever returned to clients. To address this issue, make one of the multi-homed servers the ZDC. Secure Gateway address not considered Web Interface sends the client IP address (as Web Interface sees it) to the XML Broker during application address requests, and the ZDC calculates the most appropriate server based on this information. But when the user will connect through Secure Gateway, it is the Secure Gateway server that ultimately connects to MetaFrame, not the client. The ZDC may return a server address which makes sense for REMOTE_ADDR but to which the gateway server has no route. This causes the client to receive SSL Error 37:
To resolve this issue, edit the getClientAddress() function in the Web server file include.cs to return the gateway servers internal IP address instead of REMOTE_ADDR, for example:
/** * Returns the IP address of the client. */ public string getClientAddress() { // return Request.ServerVariables["REMOTE_ADDR"]; // Use gateway IP instead of REMOTE_ADDR: return "10.12.3.45"; }
43
If the target server is not MetaFrame XP Feature Release 1 or later, only the IPv4 address resolution type is supported
44
How it works
NFuse Ticketing 1. The user provides their user name, domain, and password to the server running Web Interface and clicks an application icon. Web Interface sends a <RequestAddress> command to the XML Broker to determine the address of the MetaFrame target server. The target server will be the least busy server in the farm hosting the selected application unless the user already has a disconnected session for that application on some other server.
2. A ticket request is constructed by Web Interface that includes the users
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.
45
Note - In MetaFrame XP Feature Release 3 and earlier, this ticket request is sent to the XML Service running on the target server, which created the requirement that all servers in the farm must run the XML Service on the same port as the XML Broker. Starting with MetaFrame Presentation Server 3.0, by default the ticket request is sent via the IMA event bus using the MFServerSS IMA subsystem. 4. The target Presentation server receives the users 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 users 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 users 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 users real credentials which are still waiting in memory. The users real credentials are retrieved from memory and submitted to the WinLogon process. Note - If for any reason the credentials in the ticket request were invalid, failure would not occur until after the WinLogon substitution. CCTICKET.DLL does not validate credentials before producing a ticket.
How it breaks
Generally speaking, NFuse Ticketing fails whenever the XML Service on the target MetaFrame server is unreachable or if the target server is not licensed for ticketing.
46
Alternate addressing scenario Or, Web Interface may be configured to use Secure Gateway to enable access from the Internet, while internal users should still connect directly to MetaFrame without traversing the gateway:
47
Secure Gateway addressing scenario Because Web Interface is responsible for fostering ICA connections for all users, a determination must be made to use an appropriate addressing method for any given user based on their location. The Web Interface administrator configures address translation preferences using the Access Suite Console or by manually editing WebInterface.conf. There are a total of six unique addressing methods: 1. Direct Use the real address of the MetaFrame server, for example, Address=192.168.0.98:1494. 2. Alternate Use the alternate address of the MetaFrame server as configured by running ALTADDR.EXE on each Presentation server, for example, Address=206.31.24.99:1494. 3. Translated Similar to Alternate, but the translated address and port for each MetaFrame server are defined by Web Interface server in the Port Address Translation table instead of by running ALTADDR.EXE on each Presentation server, for example, Address=206.31.24.99:4000. 4. Secure Gateway Direct The client connects to Secure Gateway, then Secure Gateway forwards traffic to the MetaFrame Servers normal address. 5. Secure Gateway Alternate The client connects to Secure Gateway, then Secure Gateway forwards traffic to the MetaFrame Servers 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 Servers translated address. Use this method if Port Address Translation is required between the gateway and the MetaFrame Presentation servers. See the sections on Secure Gateway Integration and Secure Gateway Ticketing for more details about using Secure Gateway with Web Interface.
48
How it works
The location of the client is determined by an HTTP environment variable called REMOTE_ADDR. All Web servers maintain a REMOTE_ADDR value for each HTTP session. REMOTE_ADDR is determined by inspecting the TCP return address of the HTTP packet that arrives at the Web server. Important: REMOTE_ADDR may or may not be the end users IP address. When a client access the Web server directly, REMOTE_ADDR will equal the clients IP address; but if the clients 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.
49
If Secure Gateway and Web Interface are on separate servers but Web Interface is deployed behind Secure Gateway, change the address 127.0.0.1 in the above code to match the IP address of the Secure Gateway server as Web Interface sees it. Note that a similar change could be implanted on Web Interface 3.0 or earlier as long as Secure Gateway 3.0 is used as the reverse proxy.
50
51
How it breaks
Most cases where address translation appears to be malfunctioning are caused by confusion over the client address. For example, an administrator wishes to use Secure Gateway for all external users coming from the Internet and normal addressing for all internal users who reside on the 10.0.0.0 network. So the administrator makes what seems to be the right configuration:
ClientAddressMap=10.0.0.0/255.0.0.0,Normal,*,SG
This setting tells Web Interface to use Normal addressing for anyone whose IP address begins with 10 and Secure Gateway for anyone else. But the administrator reports that users on the Internet are being directed to the MetaFrame servers 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 clients 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 customers 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.
How it works
Workspace control features are implemented in large part by the XML and IMA Services in Presentation Server version 3.0 and later. Disconnecting from all applications When the user clicks the Disconnect button beneath their application set, an XML request is sent to MetaFrame asking the XML Broker to disconnect all current sessions for this user. Web Interface does not attempt to track which applications the user has launched; instead it defers the enumeration and disconnection of current sessions to IMA.
52
Steps to disconnect or logoff ICA sessions 1. User clicks Disconnect or Logoff. 2. Request is forwarded to XML Broker along with users 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 users credentials are included here. The success response from MetaFrame is simple:
<NFuseProtocol version="4.1"> <ResponseDisconnectUserSessions> </ResponseDisconnectUserSessions>
53
</NFuseProtocol>
The IMA Service on the XML Broker server initiates a DisconnectUserSessions() command, which publishes the event to all servers in the farm and instructs them to disconnect the users 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 users 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. Clients credentials are forwarded to XML Broker. 8. XML Broker requests ticket from target MetaFrame server(s). 9. Address and ticket belonging to target server returned to Web Interface. 10. Web Interface delivers ICA file to client. 11. Client makes ICA connection to target server and resumes the disconnected ICA session.
54
The reconnect.aspx script requests information about all the users disconnected and (optionally) active sessions in the farm, then produces an HTML page that will produce ICA files reconnecting the user to each of those applications. These two steps are shown in detail below. First, an XML request document is sent from Web Interface to MetaFrame Presentation server asking for information about currently disconnected (and in this case active) sessions for the currently logged on user:
<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_AppFriendlyNameU RLEncoded=Notepad&NFuse_HostId=9914&NFuse_HostIdType=imax002dhostx002did&N Fuse_SessionId=2" name="Reconnect0" title="Reconnect0" scrolling="yes" frameborder="yes" border="1"
55
> </frameset>
The effect of this hidden HTML frameset is the same as clicking an application icon: an ICA file is requested from Web Interface and the normal reconnection process ensues. A similar frame tag is generated for each session to which the user should reconnect. Untrusted XML Service Logoff, disconnect, and reconnect actions are security critical events that should be password protected. When Web Interface or Program Neighborhood Agent calls these commands they forward the user name and password provided by the end user for the sessions they intend to disconnect or logoff. This causes problems for smart card and single sign-on configurations because Web Interface does not have access to the users 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 users password) by default. To enable trust, run the Citrix Management Console and edit the properties of the server acting as XML Broker for Web Interface. Select Workspace Control property and enable the checkbox for Trust requests sent to the XML Service:
Enable trust for workspace control Administrators should restrict access to a trusted XML Service using firewalls, IPSec, port filtering, or any other method they see fit. Only authorized Web Interface servers should be allowed to connect to a trusted XML Service. Secure the network before enabling trust. Windows 2000 Domain Controller + IIS Port Sharing cannot be used as XML Broker When the XML Broker providing data to Web Interface is a Windows 2000 Domain Controller using IIS port sharing to deliver the XML Service, workspace control actions fail with an unspecified error. To resolve this issue, do not use IIS port sharing. Register the XML Service on a separate port by running the following commands:
ctxxmlss /r8080
56
Then reconfigure Web Interface to use the new port for the XML Service communication.
57
What happens if I already have sessions running on multiple client devices? The Disconnect and Logoff features will not affect other sessions that are already running on other client devices, but the Reconnect feature will consolidate all your sessions onto the current client device. Does this feature work with the Program Neighborhood client? Because the feature is implemented by Web Interface, it only works through a Web browser or with the Program Neighborhood Agent client. Do the workspace control buttons affect sessions that were initiated using Program Neighborhood? The Disconnect and Logoff buttons only affect applications that were launched using Web Interface from the current workstation, but the Reconnect button can reconnect you to published applications that were initiated in any way from any workstation. Custom ICA connections to server desktops are not affected.
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 users 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 5character hash that will be unique for each user. For example, tomlinjohannsebastianbach is converted to tomli-johannse-nnmnh. The shorter client name allows for more readable client printer names.
58
Secure Gateway solution architecture The Secure Gateway Administrators 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:
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://staserver/Scripts/CtxSta.dll.
Secure Gateway Settings Defined in the Access Suite Console Once the gateway FQDN and STA URLs are defined, enable Secure Gateway connectivity by creating address translation rules in the DMZ settings to direct some or all of your users through the gateway. To do so, select Manage Secure Client Access > Edit DMZ Settings:
60
Edit DMZ settings Change the default connection method to Secure Gateway Direct. You may also wish to add an exception rule that allows users on the trusted network to bypass the gateway and connect directly to Presentation Servers:
How it works
The following diagram illustrates the process by which Web Interface produces an ICA file intended for use with Secure Gateway:
61
Secure Gateway Connection Process 1. Having authenticated to Web Interface, the user clicks an application icon. 2. Web Interface contacts the XML Broker to determine the address of the target MetaFrame server. 3. The XML Broker locates the least-busy server for the chosen application and requests a MetaFrame Logon Ticket for that server. 4. The address of the target MetaFrame server and a corresponding MetaFrame Logon Ticket are returned to Web Interface. 5. Web Interface sends the target server address, user name, domain name and published application name (collectively referred to as the data) to the Secure Ticket Authority (STA) and gets a gateway traversal ticket in return. 6. Web Interface renders an ICA file for the user containing the gateway traversal ticket in the Address field. Also included in the ICA file are the following lines that instruct the client to connect to a gateway:
SSLEnable=On SSLProxyHost=csg.company.com:443
The fully-qualified domain name of the Secure Gateway server is drawn from the 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 users 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 STAs memory immediately. 9. Having validated the users ticket, the gateway opens a TCP connection to the MetaFrame servers 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.
CSG_Server value in WebInterface.conf.
62
As with non-gateway connections, the role of Web Interface is only to foster the ICA connection. Once an ICA session is established, Web Interface is no longer plays an active role in maintaining the users ICA session.
How it breaks
Web Interface configured with incorrect gateway FQDN When configuring Web Interface to support Secure Gateway connections, the administrator must enter the address of the Secure Gateway server. The address entered must match the fully-qualified domain name which appears as the Subject of the gateway server certificate. If the FQDN entered does not match the certificate on the gateway, users will receive the following error from the ICA client when an application is launched: "Security alert: The name on the security certificate does not match the name of the server (SSL error 59)."
63
6. Troubleshooting techniques
This section discusses various tips and techniques for troubleshooting Web Interface problems.
The system behavior will be such that if DuplicateLogLimit duplicate log entries have been written in a time period DuplicateLogInterval then further attempts to log the same message will not be committed to the server log. Errors resulting from incorrect user feedback (for example, supplying the wrong credentials at login) will continue to be reported with the same level of detail as before. These types of errors will not be logged. Additionally informational messages (as opposed to errors) will not be logged. As part of the system error logging feature, the Presentation Server 4.0 XML Service has been updated to replace many of the unspecified errors that it reports with a new IMA error which includes the hexadecimal error code reported by IMA. Web Interface contains a list of IMA error code to error message mappings which allows it to log the error description. The complete list of IMA Error codes is listed below.
64
Default error message: An internal error occurred" To determine the exact script and line number causing the problem, disable custom error reporting by disabling the customErrors element in <site-root>/web.config. Locate the following line in web.config:
<customErrors mode="On" 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:
65
Additional compiler information can be obtained by enabling the debug option in the web.config compilation tag:
<compilation debug="true" defaultLanguage="C#">
After resolving the issue, be sure to restore web.config to its original state so that end users do not see detailed error messages.
After saving changes, (no restart necessary), extended information will be written to the bottom of each page, including client cookies, session variables and HTTP Server Variables. You can also point your browser to <site-root>/Trace.axd and view a history of the last 100 requests. If you set pageoutput=false in web.config, trace information will not be appended to each page and you must browse to the Trace.axd page in order to view trace information. The trace.axd file does not actually exist, but the .NET framework returns information as though it did. For example:
66
Sample Trace.axd output When you click one of the View Details links, you can review all the information associated with that request at the time and a summary of how quickly each step of the process was completed. All server variables are included, which is handy when you need to determine the working value of REMOTE_ADDR for address translation troubleshooting. Here are some sample excerpts:
67
Trace detail excerpt After obtaining the information you need from the trace, be sure to disable tracing again in web.config since it may reveal sensitive information to attackers:
<trace enabled="false" />
Save the test.aspx file in the wwwroot directory and then point a browser to http://localhost/test.aspx. The output should reveal the current time. If you receive an error, then ASP.NET is failing and you should use Microsoft resources to troubleshoot the issue. Once you have the test.aspx script working, try the Web Interface URL again.
68
Or if IIS is configured to use the .NET runtime version 1.0 instead of 1.1, you may see this:
69
Source File: D:\Inetpub\wwwroot\Citrix\MetaFrame\site\web.config Line: 11 Version Information: Microsoft .NET Framework Version:1.0.3705.0; ASP.NET Version:1.0.3705.0
Aspnet_regiis.exe is installed at %SystemRoot%\Microsoft.net\Framework\Version. Full details on its usage are available in from the Microsoft TechNet Web site.
70
7. Reference Materials
7.1 Features not available on Web Interface for UNIX
Some features of Web Interface rely on core technologies provided by Microsoft Windows or Internet Information Services. These features are not available when Web Interface is running on UNIX Web servers or on Windows Web servers other than IIS. Feature 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) Program Neighborhood Agent support RDP Client RSA SecurID Authentication RSA SecurID 6.0 Password Integration Secure Computing SafeWord Authentication 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) Workspace Control Available on UNIX
New in 4.0
71
3.6.4
MetaFrame 1.8 FR1 MetaFrame XP 1.0 XML Service for Unix 1.0 NFuse 1.5 NFuse 1.51
4.1
MetaFrame XP FR1 MetaFrame for Unix 1.1 FR1 NFuse 1.6 NFuse 1.61
4.2
MetaFrame XP FR2 MetaFrame XP FR3 NFuse Classic 1.7 NFuse Classic 1.71 Web Interface 2.0 MetaFrame Presentation Server 3.0 Web Interface 3.0 Presentation Server 4.0 Web Interface 4.0
4.4 4.5
72
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.
The current IMA Error codes and their basic mnemonic descriptions are as follows:
73
IMA ID
0x80000001 0x80000002 0x80000003 0x80000004 0x80000005 0x80000006 0x80000007 0x80000008 0x80000009 0x8000000A 0x8000000B 0x8000000C 0x8000000D 0x8000000E 0x8000000F 0x80000010 0x80000014 0x80000015 0x80000016 0x80000017 0x80000018 0x80000019 0x8000001A 0x8000001B 0x8000001C 0x8000001D 0x8000001E 0x8000001F 0x80000020 0x80000021 0x80000022 0x80000023 0x80000024 0x80000025
Source Facility
SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM
ID
0x0001 0x0002 0x0003 0x0004 0x0005 0x0006 0x0007 0x0008 0x0009 0x000A 0x000B 0x000C 0x000D 0x000E 0x000F 0x0010 0x0014 0x0015 0x0016 0x0017 0x0018 0x0019 0x001A 0x001B 0x001C 0x001D 0x001E 0x001F 0x0020 0x0021 0x0022 0x0023 0x0024 0x0025
Mnemonic
IMA_RESULT_UNKNOWN_FAILURE IMA_RESULT_OUT_OF_MEMORY IMA_RESULT_INVALID_ARG IMA_RESULT_UNKNOWN_MESSAGE IMA_RESULT_DESTINATION_UNREACHABLE IMA_RESULT_REFERENCE_COUNT_NOT_ZERO IMA_RESULT_ENTRY_NOT_FOUND IMA_RESULT_NETWORK_FAILURE IMA_RESULT_NOT_IMPLEMENTED IMA_RESULT_INVALID_MESSAGE IMA_RESULT_TIMEOUT IMA_RESULT_POINTER_IS_NULL IMA_RESULT_UNINITIALIZED IMA_RESULT_FINDITEM_FAILURE IMA_RESULT_CREATEPOOL_FAILURE IMA_RESULT_SUBSYS_NOT_FOUND IMA_RESULT_PS_UNINITIALIZED IMA_RESULT_REGMAPFAIL IMA_RESULT_DEST_TOO_SMALL IMA_RESULT_ACCESS_DENIED IMA_RESULT_NOT_SHUTTING_DOWN IMA_RESULT_MUSTLOAD_FAILURE IMA_RESULT_CREATELOCK_FAILURE IMA_RESULT_SHUTDOWN_FAILURE IMA_RESULT_SENDWAIT_FAILURE IMA_RESULT_NO_COLLECTORS IMA_RESULT_UPDATED IMA_RESULT_NO_CHANGE IMA_RESULT_LEGACY_NOT_ENABLED IMA_RESULT_VALUE_ALREADY_CREATED IMA_RESULT_UID_EXCEEDED_BOUNDS IMA_RESULT_NO_EVENTS IMA_RESULT_NOT_FOUND IMA_RESULT_ALREADY_EXISTS
74
IMA ID 0x80000026 0x80000027 0x80000028 0x80000029 0x8000002A 0x8000002B 0x8000002C 0x8000002D 0x8000002E 0x8000002F 0x80000030 0x80000031 0x80000032 0x80000033 0x80000034 0x80000035 0x80000036 0x80000037 0x80000038 0x80000039 0x8000003A 0x8000003B 0x80040001 0x80040002 0x80040003 0x80040004 0x80040005 0x80040006 0x80040007 0x80040008 0x80040009 0x8004000A 0x80130001 0x80130002 0x80130003 0x80130004
Source Facility SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM SYSTEM DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION DISTRIBUTION USER USER USER USER
ID 0x0026 0x0027 0x0028 0x0029 0x002A 0x002B 0x002C 0x002D 0x002E 0x002F 0x0030 0x0031 0x0032 0x0033 0x0034 0x0035 0x0036 0x0037 0x0038 0x0039 0x003A 0x003B 0x0001 0x0002 0x0003 0x0004 0x0005 0x0006 0x0007 0x0008 0x0009 0x000A 0x0001 0x0002 0x0003 0x0004
Mnemonic IMA_RESULT_GROUP_ALREADY_EXISTS IMA_RESULT_NOT_A_GROUP IMA_RESULT_GROUP_DIR_ACCESS_FAILURE IMA_RESULT_EOF IMA_RESULT_REGISTRY_ERROR IMA_RESULT_DSN_OPEN_FAILURE IMA_RESULT_REMOVING_PSSERVER IMA_RESULT_NO_REPLY_SENT IMA_RESULT_PLUGIN_FAILED_VERIFY IMA_RESULT_FILE_NOT_FOUND IMA_RESULT_PLUGIN_ENTRY_NOT_FOUND IMA_RESULT_CLOSED IMA_RESULT_PATH_NAME_TOO_LONG IMA_RESULT_CREATEMESSAGEPORT_FAILED IMA_RESULT_ALTADDRESS_NOT_DEFINED IMA_RESULT_WOULD_BLOCK IMA_RESULT_ALREADY_CLOSED IMA_RESULT_TOO_BUSY IMA_RESULT_HOST_SHUTTING_DOWN IMA_RESULT_PORT_IN_USE IMA_RESULT_NOT_SUPPORTED IMA_RESULT_NOT_TRUSTED IMA_RESULT_MORE_ITEMS IMA_RESULT_SESSION_REQUEST_DENIED IMA_RESULT_JOB_NOT_FOUND IMA_RESULT_SESSION_NOT_FOUND IMA_RESULT_FILE_SEEK_FAILURE IMA_RESULT_FILE_READ_FAILURE IMA_RESULT_FILE_WRITE_FAILURE IMA_RESULT_JOB_CANNOT_BE_UPDATED IMA_RESULT_NO_TARGET_HOSTS IMA_RESULT_NO_SOURCE_FILES IMA_RESULT_MORE_ITEMS IMA_RESULT_INVALID_ACCOUNT IMA_RESULT_INVALID_PASSWORD IMA_RESULT_EXPIRED_PASSWORD
75
IMA ID 0x80130005 0x80130006 0x80130007 0x801300008 0x80130009 0x8013000A 0x8013000B 0x8013000C 0x8013000D 0x00130001 0x00130002 0x80060001 0x80060002 0x80060003 0x80060004 0x80060005 0x80060006 0x80060007 0x80060008 0x80060009 0x8006000A 0x8006000B 0x8006000C 0x8006000D 0x8006000E 0x8006000F 0x80060010 0x80060011 0x80060012 0x80060013 0x8006014 0x80060015 0x80060016 0x80060017 0x80060018 0x80060019
Source Facility USER USER USER USER USER USER USER USER USER USER USER DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY
ID 0x0005 0x0006 0x0007 0x0008 0x0009 0x000A 0x000B 0x000C 0x000D 0x0001 0x0002 0x0001 0x0002 0x0003 0x0004 0x0005 0x0006 0x0007 0x0008 0x0009 0x000A 0x000B 0x000C 0x000D 0x000E 0x000F 0x0010 0x0011 0x0012 0x0013 0x0014 0x0015 0x0016 0x0017 0x0018 0x0019
Mnemonic IMA_RESULT_GROUP_IGNORED IMA_RESULT_BUILTIN_GROUP IMA_RESULT_DC_NOT_AVAILABLE IMA_RESULT_NW_CLIENT_NOT_INSTALLED IMA_RESULT_ACCOUNT_LOCKED_OUT IMA_RESULT_INVALID_LOGON_HOURS IMA_RESULT_ACCOUNT_DISABLED IMA_RESULT_PREFERRED_TREE_NOT_SET IMA_RESULT_EXPIRED_ACCOUNT IMA_RESULT_ADSI_NOT_INSTALLED IMA_RESULT_SECURITY_INFO_INCOMPLETE IMA_RESULT_ATTR_NOT_FOUND IMA_RESULT_CONTEXT_NOT_FOUND IMA_RESULT_VALUE_NOT_FOUND IMA_RESULT_DATA_NOT_FOUND IMA_RESULT_ENTRY_LOCKED IMA_RESULT_SEARCH_HASMORE IMA_RESULT_INCOMPLETE IMA_RESULT_READEXCEPTION IMA_RESULT_WRITEEXCEPTION IMA_RESULT_LDAP_PARTIALINSTALL IMA_RESULT_LDAP_NOTREADY IMA_RESULT_BUFFER_TOO_SMALL IMA_RESULT_CONTAINER_NOT_EMPTY IMA_RESULT_CONFIGURATION_ERROR IMA_RESULT_GET_BASEOBJECT IMA_RESULT_GET_DERIVEDOBJECT IMA_RESULT_OBJECTCLASS_NOTMATCH IMA_RESULT_ATTRIBUTE_NOTINDEXED IMA_RESULT_OBJECTCLASS_VIOLATION IMA_RESULT_ENUMFAIL IMA_RESULT_ENUMNODATA IMA_RESULT_DBCONNECT_FAILURE IMA_RESULT_TRUNCATE IMA_RESULT_DUPLICATE IMA_RESULT_PS_NOTINITIALIZED
76
IMA ID 0x8006001A 0x8006001B 0x8006001C 0x8006001D 0x8006001E 0x80060033 0x80060034 0x80060035 0x80060036 0x80060037 0x80060038 0x80060039 0x8006003A 0x8006003B 0x8006003C 0x8006003D 0x8006003E 0x8006003F 0x80060040 0x80060041 0x80060042 0x002D 0000 0x802D0001 0x802D0002 0x802D0003 0x802D0004 0x802D0005 0x802D0006 0x802D0007 0x802D0008 0x802D0009 0x802D000A 0x802D000B 0x802D000C 0x80110104 0x80110200
Source Facility DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY DIRECTORY RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME RUNTIME LMS LMS
ID 0x001A 0x001B 0x001C 0x001D 0x001E 0x0033 0x0034 0x0035 0x0036 0x0037 0x0038 0x0039 0x003A 0x003B 0x003C 0x003D 0x003E 0x003F 0x0040 0x0041 0x0042 0x0001 0x0001 0x0002 0x0003 0x0004 0x0005 0x0006 0x0007 0x0008 0x0009 0x000A 0x000B 0x000C 0x0104 0x0200
Mnemonic IMA_RESULT_USING_ORACLE_7 IMA_RESULT_USING_ORACLE_8 IMA_RESULT_USING_ORACLE_UNKNOWN IMA_RESULT_LOAD_DAO_ENGINE_FAILED IMA_RESULT_COMPACT_DB_FAILED IMA_RESULT_ODBC_NO_CONNECTIONS_AVAILABLE IMA_RESULT_CREATE_SQL_ENVIRONMENT_FAILED IMA_RESULT_SQL_EXECUTE_FAILED IMA_RESULT_SQL_FETCH_FAILED IMA_RESULT_SQL_BIND_PARAM_FAILED IMA_RESULT_SQL_GET_COLUMN_DATA_FAILED IMA_RESULT_REPLICATED_DATA_CONTENTION IMA_RESULT_DB_TABLE_NOT_FOUND IMA_RESULT_CONNECTION_EXIST IMA_RESULT_QUERY_MAX_NODEID_FAILED IMA_RESULT_SQL_FUNCTION_SEQUENCE_ERROR IMA_RESULT_DB_CONNECTION_TIMEOUT IMA_RESULT_SQL_INVALID_TRANSACTION_STATE IMA_RESULT_DB_NO_DISK_SPACE IMA_RESULT_USING_ORACLE_9 IMA_RESULT_TRANSACTION_ROLLEDBACK IMA_RESULT_ALREADY_MASTER IMA_RESULT_TABLE_NOT_FOUND IMA_RESULT_NOT_TABLE_OWNER IMA_RESULT_INVALID_QUERY IMA_RESULT_TABLE_OWNER_HAS_CHANGED IMA_RESULT_SERVICE_NOT_AVAILABLE IMA_RESULT_ZONE_MASTER_UNKNOWN IMA_RESULT_NON_UNIQUE_HOSTID IMA_RESULT_REG_VALUE_NOT_FOUND IMA_RESULT_PARTIAL_LOAD IMA_RESULT_GATEWAY_NOT_ESTABLISHED IMA_RESULT_INVALID_GATEWAY IMA_RESULT_SERVER_NOT_AVAILABLE LMS_RESULT_NO_SERVER_AVAILABLE IMA_RESULT_FULL_SERVER_OR_APP_LOAD_REACHED
77
IMA ID 0x80260001 0x80260002 0x80300001 0x80300002 0x80300003 0x80300004 0x80300005 0x80300006 0x80300007 0x80300008 0x80300009 0x8030000A
Source Facility PRINTER PRINTER REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS REMOTE_ACCESS
ID 0x0001 0x0002 0x0001 0x0002 0x0003 0x0004 0x0005 0x0006 0x0007 0x0008 0x0009 0x000A
Mnemonic IMA_RESULT_NW_PRINT_SERVER_ALREADY_PRESENT IMA_RESULT_SERVER_ALREADY_PRESENT IMA_RESULT_SERVICE_NOT_SUPPORTED IMA_RESULT_BUILD_SD_FAILED IMA_RESULT_RPC_USE_ENDPOINT_FAILED IMA_RESULT_RPC_REG_INTERFACE_FAILED IMA_RESULT_RPC_LISTEN_FAILED IMA_RESULT_BUILD_FILTER_FAILED IMA_RESULT_RPC_BUFFER_TOO_SMALL IMA_RESULT_REQUEST_TICKET_FAILED IMA_RESULT_INVALID_TICKET IMA_RESULT_LOAD_TICKETDLL_FAILED
78
APPL_MD_PATH APPL_PHYSICAL_PATH
CERT_COOKIE CERT_FLAGS
CERT_SERVER_SUBJECT Subject field of the server certificate. CERT_SUBJECT CONTENT_LENGTH CONTENT_TYPE Subject field of the client certificate. The length of the content as given by the client. The data type of the content. Used with queries that have attached information, such as the HTTP queries GET, POST, and PUT.
79
Description The revision of the CGI specification used by the server. The format is CGI/revision. 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. Returns the value of the Accept header.
HTTP_ACCEPT
HTTP_ACCEPT_LANGUAGE Returns a string describing the language to use for displaying content. HTTP_COOKIE HTTP_HOST Returns the cookie string that was included with the request. 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). 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. Returns a string describing the browser that sent the request. Returns ON if the request came in through secure channel (SSL) or it returns OFF if the request is for a non-secure channel. Number of bits in Secure Sockets Layer connection key size. For example, 128. Number of bits in server certificate private key. For example, 1024. Issuer field of the server certificate.
HTTP_REFERER
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. The metabase path for the instance of IIS that responds to the request. 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.
INSTANCE_META_PATH LOCAL_ADDR
80
Variable LOGON_USER
Description 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. 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. A translated version of PATH_INFO that takes the path and performs any necessary virtual-to-physical mapping. Query information stored in the string following the question mark (?) in the HTTP request. The IP address of the remote host making the request. 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. 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. The method used to make the request. For HTTP, this is GET, HEAD, POST, and so on. A virtual path to the script being executed. This is used for selfreferencing URLs. The server's host name, DNS alias, or IP address as it would appear in self-referencing URLs. The port number to which the request was sent. 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. The name and revision of the request information protocol. The format is protocol/revision. The name and version of the server software that answers the request and runs the gateway. The format is name/version. Gives the base portion of the URL.
PATH_INFO
81
7.5 Debug.aspx
This ASPX script quickly reveals all active cookies, session variables and server variables, similar to the debug.asp file that was included with Project Columbia. Enlarge the font or paste the code into a text editor for viewing. For best results, save the file into the /Citrix/MetaFrame/site folder.
<% // debug.aspx // Copyright (c) 2003 Citrix Systems, Inc. All Rights Reserved. %> <script runat="server"> // Don't want passwords appearing private string password(string key, string value) { if (key.IndexOf("Password") == -1 && key.IndexOf("password") == -1 && key.IndexOf("PASSWORD") == -1) { return value; } else if (value != null) { return new String('*', value.Length); } else { return null; } } </script> <HTML><BODY> <H2>DEBUGGING INFORMATION</H2> <TABLE WIDTH=100% CELLSPACING=0 CELLPADDING=4 BORDER=1> <TR><TD VALIGN=TOP BGCOLOR=#EEEEEE> <H3>Application Variables</H3> <% for(int i=0; i<Application.AllKeys.Length; i++) { Response.Write("<B>" + HttpUtility.HtmlEncode(Application.AllKeys[i]) + "</B>"); Response.Write("=" + HttpUtility.HtmlEncode(Application[Application.AllKeys[i]].ToString())); Response.Write("<BR>"); } IEnumerator e = Application.StaticObjects.GetEnumerator(); while(e.MoveNext()) { Response.Write("<B>" + HttpUtility.HtmlEncode(((DictionaryEntry)e.Current).Key.ToString()) + "</B>"); Response.Write("=" + HttpUtility.HtmlEncode(((DictionaryEntry)e.Current).Value.ToString())); Response.Write("<BR>"); } %> </TD></TR> <TR><TD VALIGN=TOP BGCOLOR=#EEEEEE> <H3>Session Variables</H3> <% for(int i=0; i<Session.Keys.Count; i++) { Response.Write("<B>" + HttpUtility.HtmlEncode(Session.Keys[i]) + "</B>"); string obj = (Session[Session.Keys[i]] == null) ? "null" : Session[Session.Keys[i]].ToString(); Response.Write("=" + HttpUtility.HtmlEncode(password(Session.Keys[i], obj))); Response.Write("<BR>"); } %> </TD></TR> <TR><TD VALIGN=TOP BGCOLOR=#EEEEEE> <H3>Client Cookies</H3> <% for(int i=0; i<Request.Cookies.Keys.Count; i++) { Response.Write("<B>" + HttpUtility.HtmlEncode(Request.Cookies.Keys[i]) + "</B>"); HttpCookie cookie = Request.Cookies[Request.Cookies.Keys[i]]; Response.Write("=" + HttpUtility.HtmlEncode(cookie.Value)); Response.Write("<BR><LI>Expires=" + HttpUtility.HtmlEncode(cookie.Expires.ToString())); Response.Write("<BR><LI>Path=" + HttpUtility.HtmlEncode(cookie.Path)); Response.Write("<BR><LI>Secure=" + HttpUtility.HtmlEncode(cookie.Secure.ToString())); Response.Write("<BR>"); } %> </TD></TR> <TR><TD VALIGN=TOP BGCOLOR=#EEEEEE> <H3>HTTP Server Variables</H3> <% string[] serverKeys = Request.ServerVariables.AllKeys; for(int i=0; i<serverKeys.Length; i++) { Response.Write("<B>" + HttpUtility.HtmlEncode(serverKeys[i]) + "</B>"); Response.Write("=" + HttpUtility.HtmlEncode(password(serverKeys[i], Request.ServerVariables[serverKeys[i]]))); Response.Write("<BR>"); } %> </TD></TR> </TABLE> </BODY></HTML>
82