Home > Articles > Operating Systems, Server > Microsoft Servers

  • Print
  • + Share This

Citrix ICA Web Client Configuration

There are two different categories of ICA Web clients. Helper applications are provided with the following ICA clients:

  • Win32 and Win16

  • Macintosh

  • UNIX and Linux

  • Java application

A helper application's job is simple: Take an ICA file as input, parse the information, and establish a connection with the appropriate MetaFrame server. The Win32 and Win16 applications are called WFICA32.EXE and WFICA16.EXE, respectively. The UNIX/Linux application is simply called wfica, and the Macintosh and Java ICA clients are themselves the helper program.

Author's Note - These helper applications are also known as Citrix ICA client engines. If you look at the association for an ICA file after installing the latest ICA client on a Windows system, you'll see this as the description for the WFICA32 or WFICA16 client.

The following is an example of an ICA file that could be processed by one of these clients. This ICA file launches Internet Explorer, which has been configured as a published application. To process the file, you could simply execute the helper application followed by the ICA filename.

; The TcpBrowserAddress corresponds to an entry in the server location list.
; This is so the helper application knows where to look to find the master
; ICA browser, so that it can then connect to the published application,
; which in this case is Internet Explorer.
Internet Explorer=
[Internet Explorer]
Address=Internet Explorer
; The # sign before the program name signals that this is a
; published application.
InitialProgram=#Internet Explorer
TransportDriver=TCP/IPWinStationDriver=ICA 3.0

The second Citrix Web client type is the Citrix ALE client, which I discussed earlier. The ALE client's sole purpose is to process ICA files directly within a Web browser; these clients can't be run outside a Web browser. Following are the ALE clients that are currently available:

  • ActiveX control for Internet Explorer (IE)

  • 32-bit and 16-bit plug-in for Netscape or older versions of IE

  • Java applet

When a user clicks a link on a Web page pointing to an ICA file, a Citrix ALE client parses the file and establishes the connection with the published application. The following JavaScript example for the ActiveX control creates a Web page that automatically initiates a connection using the ICA file just shown. If necessary, the ActiveX control is downloaded from Citrix prior to starting the session. In the later section "Web Server Configuration," I talk in more detail about generating the HTML pages to support your Web-enabled applications.

<script language="JavaScript">
var icaFile = "remoteIE.ica";
var width = 640;
var height = 480;
var start = "Auto";
var border = "On";
var hspace = 2;
var vspace = 2;
var cabLoc = "http://www.citrix.com/bin/cab/wfica.cab#Version=4,2,274,317";
// The following is the ActiveX tag:
var activeXHTML = '<CENTER><OBJECT 
data="' + icaFile + '" CODEBASE="' + cabLoc + '" width=' + width
+ ' height=' + height + ' hspace=' + hspace + ' vspace=' + vspace
+ '> <param name="Start" value="' + start + '">
<param name="Border" value="' border + '"></OBJECT></CENTER>';

Normally the ALE client is preferred when establishing connections to Web-enabled applications, but you might want to use a helper application in the following situations:

  • You're using NFuse and you want to have seamless application connections on a Win32 client. In this case, you'll want to install the Win32 ICA client on the user's desktop.

  • You want to have a launched application instead of an embedded application. The Java applet supports only embedded applications. If you want to have a launched Java application, you need to use the Java application helper instead of the ALE Java applet.

  • You're running on a non–Windows system and don't want to use the Java applet. In this case, you can use the appropriate client helper program instead.

  • You're running a Web browser other than Internet Explorer or Netscape Navigator/Communicator. Other browsers are supported in certain situations but must rely on the helper applications to launch a published application. I discuss the supported Web browsers shortly.

ICA Client Version Requirements

The required version of either the helper or ALE client depends on whether you will be implementing Citrix NFuse. NFuse requires the latest version of these clients in order to function, but the more traditional implementation of Web-enabled applications, using the JavaScript example just shown, function with older versions of the clients. Table 15.1 lists the minimum ICA client versions required in order to use the NFuse product, which I discuss shortly.

Author's Note - Remember that all ICA clients can be downloaded for free from the Citrix Web site (http://www.citrix.com/). I recommend that you deploy the latest ICA client even if you're not planning to deploy NFuse immediately, because that option will then be open to you without requiring any future client-update planning.

Table 15.1  Minimum Required ICA/ALE Client Versions for Use with NFuse

ICA/ALE Client

Version Number











Java application


ActiveX control (ALE)


Plug-in 16/32-bit (ALE)


Java applet (ALE)


Installing an ALE Client

Helper applications are installed during the regular ICA client installation, discussed in Chapter 14, "ICA Client Installation and Configuration." The installation of the ALE client is straightforward, requiring minimal or no input from the end user. The ActiveX control and the Netscape plug-in can be installed in one of two ways:

  • From the Citrix ICA Web Client installation source. The ActiveX control is installed by running WFICA32.EXE /SETUP from the ActiveX directory in the installation location. The plug-in is installed by running either WFPLUG16.EXE or WFPLUG32.EXE from the NSPlugin directory. In both cases, you need to stop the browser before performing the installation and restart the browser afterwards to begin using the new client. The client must be installed in this manner in order to launch an application.

  • Automatically over an intranet or the Internet. You can configure your Web page to download the necessary client files automatically to the user if he or she doesn't already have them when connecting to your site. If the user is using IE, the ActiveX control can be downloaded and started automatically. The Netscape plug-in will be downloaded but will require the user to initiate the installation process manually. After this is done, the user will be able to begin using the Web client. The auto-loaded client will only function with embedded applications. It cannot be used for application launching. In order to support launching, the ActiveX or Plug-in client must be manually installed as described in the previous bullet.

The ActiveX HTML source looks similar to the following, which retrieves the ActiveX control from the Citrix site if required:

<CENTER><OBJECT classid="clsid:238f6f83-b8b4-11cf-8771-00a024541ee3"
data="remoteIE.ica" CODEBASE=" http://www.citrix.com/bin/cab/wfica.cab#
Version=4,2,274,317" width=640 height=480 hspace=2 vspace=2>
<param name="Start" value="Auto"><param name="Border"

The plug-in source looks like this:

<CENTER><EMBED SRC="remoteIE.ica" pluginspage=" http://www.citrix.com/demoroom/
plugin.htm" width=640 height=480 start=Auto border=On hspace=2

The Java applet requires no explicit installation on the client. Instead, it's installed and configured on the Web server, where it's accessed when the user clicks a link configured to run with the Java applet. To use the Java applet, the browser must support the JDK 1.1 or higher. A 1.0 version of the Java client is available from the Citrix Web site if you need to support older browsers (such as Netscape Navigator 3.x) that don't have a 1.1-compliant JDK.

Author's Note - If you want to run the Java client in application mode, you need to install the ICA Java client on the user's local computer. I discuss these installation steps in the next section.

ICA Java Client

The Citrix ICA Java client allows you to access a published application from a Java Virtual Machine (JVM). This can be a JVM running on any operating system, a Web browser that supports Java applets, or a Java-based device. A number of browsers are supported not only on Windows platforms, but also on UNIX, Macintosh, and OS/2.

Depending on how you use the Java client, it runs in one of two modes: application or applet mode. Both operation modes use the same set of class files.

  • Application mode. In this mode, the Java client resides on the user's computer, along with a valid JVM. A published application is usually accessed by executing the Java client from the command line, with the help of the JVM. The application on the MetaFrame server then starts as its own window on the client desktop. I discuss application mode in more detail in the "Java Helper Application" section later in this chapter. To run in application mode, the JVM must support the JDK 1.1 or higher.

  • Applet mode. As discussed earlier, in this mode the Java client resides on a Web server. Users access MetaFrame sessions by using a Web browser that has Java support. To run in applet mode, the browser must support JDK 1.1 or higher.

Troubleshooting Tip - Neither Internet Explorer 3.x or earlier nor Netscape Navigator 3.x or earlier have a 1.1-compliant JDK. To access a MetaFrame Java applet using one of these browsers, you need the JDK 1.0-compliant version of the Citrix ICA Java client. This is available from Citrix's Web site.

The ICA Java client doesn't provide full support for all the ICA client features found with the Windows clients. The supported features are as follows:

  • Client audio, printer, and COM port mapping

  • Clipboard sharing (text only, no graphics)

  • Multiple server location entries (also known as the business recovery option)

  • Data compression and SpeedScreen2

  • Auto-reconnect to an existing session and shadowing

  • Encryption (only basic encryption)

  • Program Neighborhood

The Java client has the following limitations:

  • No support for seamless windows

  • No persistent bitmap caching

  • Supports only 256 colors (not 16)

  • Supports only the TCP/IP protocol

  • No support for client drive mappings

Installing the Java Client

To access a published application or Program Neighborhood through a Java applet, the necessary Java classes need to be installed on the Web server. If you'll be running the Java client directly on a user's desktop, you need to install the classes locally. For either situation, the installation is the same and is performed as follows.

Author's Note - Because the exact JVM implementations differ between operating systems, the installation steps are not identical for all of them. I've included notes for both Windows and Linux in this example. For specific installation information on other platforms, review the documentation that accompanies the ICA Java client installation files.

  1. Create the directory in which you will install the client. In this example, I'll use the directories d:\JICA11 for Windows and usr/lib/jica11 for Linux. If you're installing the client on a Web server, make sure that this directory is accessible by your users. A common location is in a jica11 directory off the root Web directory.

  2. Copy Setup.class into this directory. This file can be found on the MetaFrame CD in the ICACLNT\ICAJAVA directory. It can also be downloaded from the Citrix Web site.

  3. Run Setup.class and install the Java classes into this directory. You run Setup.class by launching it with the appropriate JVM for your operating system. The general syntax is as follows:

    <full path>\<jvm> setup

    where <full path> is the full path to the <jvm>. On the Win32 platform, Microsoft's JVM is JVIEW.EXE and is located in the %systemroot% directory. On Linux, the Sun JVM (downloadable from http://www.sun.com/) is java.

  4. Running Setup.class starts the InstallShield Installation Wizard (see Figure 15.7), which guides you through installing the classes. You'll be prompted to provide the destination for the class files. Specify the directory that you created in step 1. All required files are then installed into the destination location.

  5. As part of the installation, two batch scripts are created in the destination directory that can be used to start the Java Program Neighborhood or launch individual ICA files (Java helper application). I'll talk about both of these shortly.

Figure 15.7
The Citrix ICA Java client installation wizard.

If you're installing the client on a Web server, you need to create a Web page that will launch either an individual published application or Program Neighborhood with the Java applet when visited by users. I talk about this in the later section "Web Server Configuration."

Java Program Neighborhood

During the installation, the setup program detects the OS that the client is running as well as the JVM being used and generates the appropriate script file to launch the Java version of Program Neighborhood. The created script is called pnsession.<ext>, where <ext> is the appropriate batch extension for the client OS. For example, on Windows the script would have the extension .BAT. On Linux, no extension would be assigned, and the script would simply be called pnsession. When using Microsoft's JVM, the Program Neighborhood script would look similar to the following:

@echo off
REM This file was generated by InstallShield
REM Created on Fri Feb 18 13:01:17 EST 2000 by toddm
"jview" /cp:p "D:\JICA11\.;D:\JICA11\JICAEngJ.jar" com.citrix.pn %1 %2 %3 %4 %5
%6 %7 %8 %9

Online help is available from within Program Neighborhood, but to make it work properly you must modify the generated script by adding the /d: or -d option, depending on your JVM. For the Microsoft script just shown, I would add the following immediately after the "jview" text:


On Linux, using Sun's java JVM, I would add the following:


Without this entry, you'll get the message shown in Figure 15.8 when you attempt to open the PN help.

Figure 15.8
Java PN help error message.

To run the script, simply open a command prompt and run PNSESSION.BAT. The main Program Neighborhood window (see Figure 15.9) should open, appearing almost identical to the one available with the native Win32 client.

Figure 15.9
Java Program Neighborhood.

Many of the features and functions found in the Win32 PN are also available in the Java PN. For more information on Program Neighborhood, see Chapters 3 and 14.

The following restrictions apply to the Java PN in comparison with the Win32 version:

  • Only the TCP/IP protocol is supported.

  • Seamless window sessions are not supported.

  • Dial-up ICA connections are not supported.

  • A default server farm must always be selected.

  • Bitmap caching is not configurable, although the Java client does utilize SpeedScreen.

Java Helper Application

The other script file created during the Java client setup is the ICA helper script called jicasession.<ext>, where <ext> is the appropriate batch extension for the client OS. For example, on Windows the script would have the extension .BAT. On Linux, no extension would be assigned, and the script would simply be called jicasession. When using Microsoft's JVM, the helper script would look similar to the following:

@echo off
REM This file was generated by InstallShield
REM Created on Fri Feb 18 13:01:16 EST 2000 by toddm
"jview" /cp:p "D:\JICA11\.;D:\JICA11\JICAJ.jar" com.citrix.JICA %1 %2 %3 %4 %5 
%6 %7 %8 %9

Notice that this script uses the JICAJ.JAR file instead of the one containing Program Neighborhood. To test the script after installation, simply open a command prompt and change into the directory containing your Java client files. Then execute this command:

jicasession -address:<MF Server>

where <MF Server> is the name of a MetaFrame server.

For example, to connect to a MetaFrame server called ORCA, I would enter this command:

jicasession -address:ORCA -width:800 -height:600

This will open a connection to the ORCA server with a window size of 800x600. A number of parameters exist for the Java client, in both application and applet modes. Table 15.2 lists some of the commonly used parameters. Each parameter is preceded by a hyphen (-) and uses a semicolon (:) as the separator between the parameter and the actual data value. For a complete list of options, consult the "ICA Java Client Parameters" section of the HTML help file installed with the ICA Java client. It can be found in the help subdirectory where you installed the Java client.

Table 15.2  Common Java Helper Application Options




Specifies the name of a server or published application. If this is a published application, you must also specify the InitialProgram parameter.


The name of the program to run after connecting to the server. If this is a published application, you must include the # symbol at the beginning of the name. For example, if the application is called IE, you enter #IE.


The working directory for the initial program. If InitialProgram is a published application, this is not required.


Specifies a directory location where INI file information can be stored for the Java client. Using this parameter allows the storing of client printer information so that it can be reloaded automatically in later sessions.


Used when a client is on a different subnet than the Citrix servers containing the published application. You provide the IP address or fully qualified domain name of a Citrix server on the target subnet. X is either blank or a number from 2 to 15, signifying the server location for business recovery. Blank through 5 are the primary group, 6 through 10 are the secondary group, and 11 through 15 are the tertiary group.


Specifies a username to use during logon.


Specifies the domain to use during logon.


The password for the user.

Warning - Of course, if you provide the password from the command line, it will appear in plaintext. I recommend that you never provide a password from a command line or a script file.

You can also pass a predefined ICA file to jicasession by simply passing it as a parameter without any switches. For example, to connect to a MetaFrame server using an ICA file called remoteIE.ica, you would enter the following:

jicasession remoteIE.ica

Author's Note - Entering jicasession without any parameters launches the GUI command prompt. This is a graphical window where you can enter any of the parameters you normally would enter from a command prompt. This is mainly used to allow Macintosh users to enter the various parameters because they don't have a command prompt from which to run the Java client in application mode.

Java Security Issues

Because of network security restrictions that exist in Java, Web browsers normally are unable to access other computers on the network when running a Java applet. Only resources on the same machine as the Java classes are accessible. Under these conditions, an attempt by the ICA Java applet to connect to a MetaFrame server across the network will fail because of the security violation. Figure 15.10 shows the message that appears in this situation.

Figure 15.10
Java security denying access to a MetaFrame server on the network.

Fortunately, you can deal with this security restriction in three ways:

  • Locate your Web server and your MetaFrame server on the same physical machine. This way, when the Java applet is started, it accesses the Web pages and MetaFrame server locally. This is allowed by Java security. Of course, this doesn't allow you to access a published application load-balanced across multiple servers. While this technique will resolve the security issue, I don't recommend it, since it not only introduces additional load on the MetaFrame server (since you're now also running the Web service), but also limits your ability to expand Web-enabled applications beyond the one server.

  • Maintain your Web server separate from your MetaFrame server, but locate the ICA Java classes on the MetaFrame server. The links on the Web page will reference the Java classes, which reside on the MetaFrame server. Java security will allow the applet to connect to the MetaFrame server. While this separates the Web service from the MetaFrame server, just as in the preceding option it limits connections to that specific server and doesn't take into consideration accessing a published application.

  • Use "signed" Java class archives. These specially "signed" files verify that they came from Citrix and have not been altered in any way by someone else. Browsers that understand signed Java archives allow connections to a Citrix server that's not the same machine as the Web server that contains the ICA Java classes. To access published applications, you must use the appropriate signed Java class archive. I discuss these archives next.

Signed Java Class Archives

The Setup.class installation file includes six different signed Java class archives. Which archive is used depends on the type of browser or JVM used by the client and whether Program Neighborhood functionality is desired. If the browser or JVM doesn't support any of these archive types, they can still access the extracted class files, although they will be restricted by the Java security issues described in the preceding section. The class files can be extracted using a tool such as WinZip that understands Java archives. The six archives available are as follows:

  • JICAEngM.cab. Signed cabinet (CAB) file containing Program Neighborhood. It can be used by any browser or JVM that supports running Java programs from CAB files. CAB files allow Internet Explorer to work around Java network security, which prevents Java applications running on one machine from accessing resources on another. The security safety level for active content must be set to Medium in IE in order to use the signed CAB file.

  • JICAEngJ.jar. Signed Java Archive (JAR) file containing Program Neighborhood, which can be used by any browser or JVM that supports running Java programs from JAR files. For example, this JAR allows the HotJava browser to work around Java network security. This JAR is the default used by the setup program when creating the helper and Program Neighborhood scripts (discussed shortly).

  • JICAEngN.jar. JAR file containing Program Neighborhood, specifically for the Netscape browsers.

  • JICAM.cab. Internet Explorer CAB file without Program Neighborhood support.

  • JICAJ.jar. JAR file without Program Neighborhood support.

  • JICAN.jar. Netscape JAR file without Program Neighborhood support.

I discuss using the appropriate Java class archive in an HTML file in the "Web Server Configuration" section of this chapter.

Supported Web Browsers

The list of supported Web browsers for accessing Web-enabled applications depends on whether you'll use NFuse to provide your users with access to published applications or if you'll provide application links on a Web page.

NFuse Browser Support

Table 15.3 lists the supported Web browser and ICA/ALE client combinations when using NFuse. As you can see, currently only Internet Explorer and Netscape Navigator/Communicator are supported with NFuse.

Table 15.3  Supported Web Browsers for Use with NFuse

ICA/ALE Client

Supported Web Browsers


Internet Explorer 4.0+

Java application

Netscape Navigator 4.01+

Java applet (ALE)


ActiveX Control (ALE)


Plug-in 16-bit or 32-bit (ALE)



Internet Explorer 4.01+


Netscape Navigator 4.08+


Netscape Navigator 4.01+


Netscape Communicator 4.61+


Netscape Navigator 4.01+


Netscape Communicator 4.61+

Web-Enabled Published-Application Browser Support

When accessing a published application directly from a link on a Web page, almost any Web browser is supported. Table 15.4 lists the supported ALE/Web browser combinations in this situation and indicates whether launching or embedding is supported.

Table 15.4  ALE Clients and Supported Web Browsers in Non–NFuse Configurations

ALE Client


Supported Web Browsers

ActiveX control


Internet Explorer 3.x or higher on a Windows 32-bit OS.



Netscape Navigator 2.02 or higher on 16-bit or 32-bit Windows.

Java applet

Embedding only

If using signed archives, it depends on whether the browser supports a signed archive. Netscape, Internet Explorer, and Sun HotJava all support signed archives. If you're using unsigned archives, any browser that supports JDK 1.1 should be usable.

Tip - In order to use the ActiveX or Netscape plug-in to launch an application, the Web client must first be installed on the user's desktop using WFICA32.EXE 1 setup, WFPLUG16.EXE, or WFPLUG32.EXE. The client cannot be automatically loaded as it can with an embedded application. See the section "Installing an ALE Client" earlier in this chapter for more information.

Even if a browser doesn't support an ALE client, it can still provide application launching if the browser supports configurable MIME types. Application embedding is supported only with the Citrix ALE clients. The MIME type is configured with the following information:

Mime type:


File extension:


View/helper program:

Specify an appropriate helper application, depending on the ICA client. For example, the helper application for the Win32 client is WFICA32.EXE, and the Java client's helper is jicasession.

Author's Note - The latest versions of all ICA clients supported by NFuse (refer to Table 15.1, earlier in this chapter)—except for the Java and Macintosh clients—automatically configure their helper applications to work with Internet Explorer or Netscape during installation. If you want to use the Java or Macintosh clients, or if you want to configure a different browser to use a helper application, you must configure the proper MIME type for your browser manually.

Configuring the Web Browser

Unless your Web browser requires a manually configured MIME type to support application launching, you're not required to perform any specific Web browser configuration prior to accessing a Web-enabled published application. You can also manually install the ActiveX control or the Netscape plug-in using the Web installation files, as discussed in the earlier section "Installing an ALE Client."

Exactly how you configure a MIME type depends on which browser you're using. For example, with Netscape you define the helper application by selecting the View, Preferences menu option. Figure 15.11 shows the configuration of the MIME type for Netscape so that the application script JICASESSION.BAT will be used to launch published applications from a Web page using the ICA Java application.

Figure 15.11
The ICA Java client defined as a helper application for Netscape Communicator.

To perform a similar configuration with Internet Explorer on a 32-bit Windows OS, you must edit the file type properties for the OS. This is done by opening a folder and selecting Tools, Folder Options from the menu. Then select the File Types tab and click New Type to open a screen similar to the one shown in Figure 15.12. For IE on Macintosh, the MIME settings are found under the Edit, Preferences menu option. You'll need to configure a new File Helper under the Receiving Files section in the left panel.

Figure 15.12
Configuring the ICA helper application for Internet Explorer on an NT 4.0 workstation.

If you'll be using the Java client as an applet with Internet Explorer, set the security safety level in order to properly use signed CAB files, as shown in Figure 15.13.

Figure 15.13
Setting the security safety level in IE5 to support signed CAB files.

  • + Share This
  • 🔖 Save To Your Account

Related Resources

There are currently no related titles. Please check back later.