The Citrix ICA file explained and demystified

Citrix-ICA-icon4

The Citrix Receiver (XenApp plugin / Online plugin / ICA Client / WinFrame client) has a file association with the .ICA extension. This means that each time you open a file with the .ICA extension the Citrix Receiver is launched to interpret the file (and act upon the content of the file).

In this article I’ll explain how the .ICA file is constructed, what sections and properties are commonly used and how you can create the file.

ICA – Independent Computing Architecture

image_thumb5To start at the beginning, ICA stands for Independent Computing Architecture. It is a protocol used in Citrix XenApp / XenDesktop (or previously Presentation Server, MetaFrame, WinFrame) to separate the application logic (which runs on a remote system, usually in a datacenter) and the presentation (on the client).

In a nutshell what this protocols does is sending input from the client (like keyboard, mouse, audio, etc.) to the remote system and receive the output (like video, sound, etc.) from the remote system via the network. On the client (a workstation, laptop or thin client) a piece of software is used to handle this traffic. At the moment of this writing the Citrix Receiver is used.

Files with the extension .ICA contain information required to connect to the remote system, including session properties and (optionally) authentication.

.ICA File

File Type Association (FTA)

Files with an .ICA extension are associated with a Citrix ICA client. This is done via a File Type Association (or FTA).

HKCR_ICA_thumb4In the registry hive HKEY_CLASSES_ROOT a key with the name .ica specifies the name of the file type and the content type.

  • Name: Citrix.ICAClient.2.7
  • ContentType: application/x-ica

HKCR_Citrix.ICA.Client.2.7_thumb1The name is correlated to the key HKEY_CLASSES_ROOT\<key name> and describes how the file is handled, what icon to show, what items should be visible in context menu etc.

In the shell\open\command key the default value shows what executable to run when a file with the .ICA file extension is launched. In my case:

"C:\Program Files (x86)\Citrix\ICA Client\wfcrun32.exe" "%1"

Basic structure

.ICA files are stored in plain text with ISO/IEC 8859 encoding (except for older ‘legacy’ clients) so they can easily be viewed and edited in a basic text editor. The content is stored in the INI file format with a basic structure composed of “sections” and “properties”.

Properties are stored in separate sections, recognizable by the square brackets [ and ]. In a basic ICA file the following three sections are present:

[WFClient]

[ApplicationServers]

[%ConnectionName%]

Each section has properties (or settings) assigned, some of there are mandatory but most are optional. In the next sections I’ll explain the most common settings and the not-so-common settings that are available.

Properties per section

Each section contains a list of properties (or settings) that can be set. I’ll describe the most common settings per section, a larger (not complete) list of properties can be found in the ICA Settings Reference on Citrix eDocs.

[Encoding] (Optional)

This section contains setting(s) that describe how the file is encoded.

Example
[Encoding]
InputEncoding = ISO8859_1

In the example the .ICA file is stored in the default encoding, ISO8859_1.

Settings
  • InputEncoding
    • Description: Describes the character encoding type of the .ica file. This information is used by the client to convert and understand the .ica file if the Web server that created it used an encoding type that is different from that of the the client.
    • Possible values:
      Value Description
      ISO8859_1 ISO/IEC 8859 is a joint ISO and IEC series of standards for 8-bit character encodings (Default, according to Citrix eDocs)
      SJIS Shift_JIS is a character encoding for the Japanese language
      EUC-JP Extended Unix Code (EUC) is a multibyte character encoding system used primarily for Japanese, Korean, and simplified Chinese.
      UTF8 UCS Transformation Format – 8 bit is a variable-width encoding that can represent every character in the Unicode character set (Default for WebInterface launch.ica)

 

[WFClient]

In this section the client is configured. WFClient stands for WinFrame client, so it goes way back Knipogende emoticon

Example
[WFClient]
Version=2
RemoveICAFile=Yes
HttpBrowserAddress=server01.domain.local:80
ConnectionBar=1

In the example a server with the name server01.domain.local is contacted on port 80 to supply details about the server or published application / desktop that is supplied in the [ApplicationServers] section. During the connection the Desktop Viewer is used and a Connection Bar is shown. After the connection is broken the .ICA file is removed.

Settings
  • AlwaysSendPrintScreen
    • Description: Enables or disable using the Print Screen key on the keyboard while the ICA session is running with seamless application.
    • Possible values:
      Value Description
      On Print Screen key can be used
      Off Print Screen key cannot be used (Default)
  • CDMAllowed
    • Description: Specifies whether Client Drive Mapping (CDM) is allowed or not.
    • Possible values:
      Value Description
      True Allow Client Drive Mapping (Default)
      False Disallow Client Drive Mapping
  • ConnectionBar
    • Description: Enables or disable the use Desktop Toolbar (and the Desktop viewer) for all connections in the .ICA file. More details can be found here.
    • Possible values:
      Value Description
      0 The ICA Client (wfcrun32.exe) is used instead of the Desktop viewer (cdviewer.exe) (Default)
      1 The desktop viewer (cdviewer.exe) is used instead of the ICA client (wfcrun32.exe).
  • EnableSSOnThruICAFile
    • Description: Specifies whether or not to use the same user name and password the user used to log on to the client device for authentication through .ica files. For security reasons, users cannot be authenticated to the server unless this parameter is present and its value set to On, even if UseLocalUserAndPassword and SSOnUserSetting are specified in the .ica file.
    • Possible values:
      Value Description
      On / True / 1 / Yes Use same username and password
      Off / False / 0 / No Do not use same username and password (Default)
  • HttpBrowserAddress
    • Description: Specifies the location of the browser server (usually the data collector since it holds the most accurate information of the farm).
    • Possible values:
      Value Description
      <FQDN>:<port> The Fully Qualified Domain Name (for instance server01.domain.local) of the browser server followed by a colon and the port where the XML service is located (default port is 80)
      <IP>:<port> The IP address of the browser server followed by a colon and the port where the XML service is located (default port is 80)
  • RemoveICAFile
    • Description: Specifies whether or not the ICA file should be deleted after the session is finished. The setting is set either by Off, False, no or 0 (or the opposite value)
    • Possible values:
      Value Description
      Off / False / no / 0 Does not remove ICA file (Default)
      On / True / yes / 1 Removes ICA file
  • Version
    • Description: The version of the ICA file structure.
    • Possible values:
      Value Description
      2 Version two of the ICA file structure. No other version is known? (Default)
[ApplicationServers]

Contains one (or more) connections that are stored in the file. The “more” connections is a legacy option used in the Program Neighborhood that has been removed in version 11.1 – CTX121727 (june 2009), the connections where stored in the appsrv.ini which had the same structure as the ICA file.

Example
[ApplicationServers]
Desktop=

In the example a connection with the name Desktop is present. When the .ICA file is executed by the client software, the properties are read in [Desktop].

Settings
  • %ConnectionName%
    • Description: The name of the connection, the properties of this connection are located in the section with the name name (%ConnectionName%). Depending on the version of the client this name is (shortly) visible for the user during the connection phase.
    • Possible values: None
[%ConnectionName%]

The section has the name of the connection that is supplied in the ApplicationServers ‘list’. In this section the properties are set for the connection. This is the most extensive list and therefore segregated in separate areas.

Example
[Desktop]
Address=Desktop
InitialProgram=#Desktop
CGPAddress=*:2598
ClientAudio=On
DesiredColor=8
TWIMode = True
ConnectionBar=1
TransportDriver=TCP/IP
WinStationDriver=ICA 3.0
Compress=On
EncryptionLevelSession=Encrypt

In the example the settings for the connection Desktop are supplied. A seamless connection will be made to the published application Desktop with a connection bar (and the Desktop Viewer) visible. Both Session Reliability as Client audio are enabled. The connection is made with compression and encryption enabled whose details are specified in section [Compress] and [Encrypt].

Settings – General

This area describes the general properties of the connection.

  • Address
    • Description: Specifies where the Citrix client should connect to
    • Possible values:
      • Connect directly to server: The FQDN of the Citrix XenApp / XenDesktop server
      • Connect to published application / desktop : The name of the published application / desktop
      • Connect via WebInterface / CloudGateway: A semicolon (;) separated string containing the application / desktop to connect to, the secure ticket authority (STA) and the secure ticket (or token). The user can click an application / desktop and will effectively download a launch.ica which will be processed by the Citrix client (receiver).
  • CGPAddress
    • Description: Enables or disables Session Reliability
    • Possible values:
      Value Description
      *:2598 Session Reliabilty is used (connection is made on port 2598)
      (empty) Session Reliability is not used (connecion is made on port 1494)
  • Compress
    • Description: Specifies whether the ICA traffic needs to be compressed before its transported.
    • Possible values:
      Value Description
      On ICA traffic is send compressed. The driver used to compress is specified in section [Compress]
      Off ICA traffic in send uncompressed
  • InitialProgram
    • Description: Specifies what application to launch
    • Possible values:
      • Connect directly to server: The location to the executable to launch. If the value is empty the default shell is loaded.
      • Connect to published application / desktop : A hash-sign (#) followed by the name of the published application / desktop
  • Launcher
    • Description: Specifies the name of launch mechanism (that is, the client launcher name). This parameter is used to launch multiple ICA windows from the startup folder at logon time.
    • Possible values:
      Value Description
      ICA Client Launched using the ICA client (default)
      WI Launched through the Web Interface
      PN Launched through the Program Neighborhood client (deprecated)
      PNAgent Launched through the Program Neighborhood agent
      MSAM Launched through the Metaframe Secure Access Manager
      Custom Launched through a custom client
  • LaunchReference
    • Description: Reference token for a specific session on a Citrix XenApp server. This enables the Citrix SmoothRoaming feature, it directs the user to the same server as it has an existing session.
    • Possible values: Reference token for a specific session on a server (generated by the WebInterface).
  • LogonTicket
    • Description: Specifies client authentication token for web interface. The client handles an authentication token in the form of an opaque LogonTicket with an associated interpretation defined by the LogonTicketType. This functionality can be disabled by clearing the Web Interface 4.5 and above check box.
    • Possible values: A token in the form of a serialized string provided by the WebInterface
  • LogonTicketType
    • Description: Specifies the logon ticket type for “Web interface authentication ticket”. Use this policy to control the ticketing infrastructure used when authenticating through the Web Interface. The client handles an authentication token in the form of an opaque LogonTicket with an associated interpretation defined by the LogonTicketType. Citrix STA versions are described in CTX108302.
    • Possible values:
      Value Description
      0 No ticket (default)
      1 Secure Ticket Authority (STA) version 1 ticket
      2 Secure Ticket Authority (STA) version 4 ticket
      CTXS1 Secure Ticket Authority (STA) version 4 ticket (?)
  • PersistentCacheEnabled
    • Description: This parameter specifies whether or not to use the persistent disk cache. The persistent disk cache stores commonly used graphical objects such as bitmaps on the client device’s hard disk.
    • Possible values:
      Value Description
      On The persistent cache is enabled
      Off The persistent cache is disabled (Default)
  • SessionSharingKey
    • Description: Specifies the session sharing key. The sharing key is a combination of all attributes that allows you to reuse an existing session: colors, encryption, audio, credentials and farm. If any of these attributes are different (not 100% identical), a new session is created. For more information read the article of Thomas Koetzing about this topic.
    • Possible values:
      • Web Interface 4.6 and before : colors – encrypt – audio – domain – user farm
      • Above Web Interface 4.6: A serialized string containing the same information
  • SSLEnable
    • Description: Specifies whether or not SSL is enabled. When SSL is enabled all ICA traffic (1494 or 2598) is tunneled via a secure socket layer (SSL) tunnel via port 443 (by default).
    • Possible values:
      Value Description
      On ICA traffic is tunneled via SSL
      Off ICA traffic is not tunneled via SSL (Default)
  • SSLProxyHost
    • Description: Specifies the hostname of the SSL proxy when SSLEnable is set to ‘On’. This value is not present when traffic is not tunneled via SSL. The name on the certificate has to match the hostname (FQDN).
    • Possible values:
      Value Description
      *:443 It is assumed that all Citrix server in the farm have their own SSL relay, the SSL relay is the same as the Citrix server. (Default)
      <FQDN>:443 An explicit server is specified as the SSL relay server (for instance an Citrix Access Gateway).
  • TransportDriver
  • UseAlternateAddress
    • Description: This parameter is useful in performing Network Address Translation (NAT). If set to 1, it defines whether to use the alternate address for ICA connectivity across a firewall or a router.
    • Possible values:
      Value Description
      0 Do not use the alternate address for firewall connection option (Default)
      1 Use alternate address for firewall connection option.
  • WorkDirectory
    • Description: Specifies the working directory for the InitialProgram
    • Possible values:
      • Connect directly to server: The working directory of the program to execute (instead of the default shell)
      • Connect to published application / desktop : Not used
  • WinStationDriver
    • Description: Specifies what winstation driver to use, the driver where all ICA (including virtual channels) traffic flows through
    • Possible values:
      Value Description
      ICA 3.0 The only valid value is ICA 3.0. Previous versions where used before WinFrame (Windows NT 3.5). (Default)
Settings – Audio

This area describes the settings that relate to audio [HDX].

  • AudioBandwidthLimit
    • Description: Specifies the audio bandwidth limit and, by extension, the audio quality for the connection. Higher audio quality requires more bandwidth.
    • Possible values:
      Value Description
      0 High quality (1.4 Mbps)
      1 Medium quality (64 Kbps) (Default)
      2 Low quality (4 Kpbs)
  • ClientAudio
    • Description: Specifies whether or not to enable client audio mapping.
    • Possible values:
      Value Description
      On Enables client audio mapping
      Off Disables client audio mapping (Default)
  • EnableAudioInput
    • Description: Enable access to audio capture devices. Use this policy to enable and restrict the remote application or desktop access to local audio capture devices (like microphones).
    • Possible values:
      Value Description
      True Allow the use of audio capture devices
      False Disallow the use of audio capture devices
  • EnableRtpAudio
    • Description: Enables or disables the real-time transport of audio over UDP.
    • Possible values:
      Value Description
      True Enables Rtp Audio (Default)
      False Disables Rtp Audio
  • SpeedScreenMMAAudioEnabled
    • Description: Specifies whether or not audio playback will occur through HDX MediaStream Multimedia Acceleration.
    • Possible values:
      Value Description
      True Audio playback will occur through HDX MediaStream Acceleration(Default)
      False Audio playback will not occur through HDX MediaStream Acceleration
Settings – Display

This area describes the settings that relate to display like color depth, resolution and video [HDX].

  • DesiredColor
    • Description: Specifies the preferred color depth for a session.
    • Possible values:
      Value Description
      1 16 colors (Default)
      2 256 colors
      4 High color (16 bpp)
      8 True color (24/32 bpp). This is 32bpp, unless the administrator explicitly prohibits a server from supporting a 32-bit session. In that case, the session is downgraded to 24bpp.
  • DesiredHRES
    • Description: This parameter defines the horizontal window size in pixels.
      • For Citrix Receiver and up : If TWIMode is set to Off / False, this parameter is used.
      • For older Citrix clients: If DesiredWinType is set to Custom, this parameter is used.
    • Possible values: The horizontal window size in pixels (Default : 640). If you set both DesiredHRES and DesiredVRES to 4294967295 the session will always launch in full screen (thanks Andrew Morgan).
  • DesiredVRES
    • Description: This parameter defines the vertical window size in pixels.
      • For Citrix Receiver and up : If TWIMode is set to Off / False, this parameter is used.
      • For older Citrix clients: If DesiredWinType is set to Custom, this parameter is used.
    • Possible values: The vertical window size in pixels (Default : 480.) If you set both DesiredHRES and DesiredVRES to 4294967295 the session will always launch in full screen (thanks Andrew Morgan).
  • DesiredWinType
    • Description: This parameter specifies the default desired window size for custom connections. This setting is ignored by the Citrix Receiver.
    • Possible values:
      Value Description
      1 640×480
      2 800×600
      3 1024×768
      4 1280×1024
      5 Custom size defined by DesiredHRES and DesiredVRES
      6 Percent
      7 Full Screen
      8 Seamless
  • SpeedScreenMMA
    • Description: Specifies whether or not to enable the HDX MediaStream Multimedia Acceleration.
    • Possible values:
      Value Description
      On The remote video option allows the server to directly stream certain video data to the client (if the client has the appropriate codecs). (Default)
      Off The video is always rendered on the client.
  • TWIMode
    • Description: Specifies whether or not to use seamless mode for the connection.
    • Possible values:
      Value Description
      On / True Enables the seamless mode for the connection
      Off / False Disables the seamless mode for the connection (Default)
Settings – Security

This area describes the settings that relate to security.

    • ClearPassword
      • Description: The parameter specifies the password for the supplied credentials in clear text. This is less safe than the encrypted Password setting.
      • Possible values: A password.

  • EncryptionLevelSession
    • Description: Specifies the encryption level of the ICA connection (SecureICA). Since the Citrix Receiver a section with the corresponding name should be provided including the drivers.
    • Possible values:
      Value Description
      Basic Basic (Default)
      EncRC5-0 RC5 (128 bit – Logon Only)
      EncRC5-40 RC5 (40-bit)
      EncRC5-56 RC5 (56-bit)
      EncRC5-128 RC5 (128 bit)
      Encrypt Basic
  • Domain
    • Description: This parameter specifies the user domain for the supplied credentials.
    • Possible values: The name of the domain for the supplied credentials.
  • Password
    • Description: This parameter specifies the password for the supplied credentials. The password must be encrypted.
    • Possible values: An encrypted password. Remko Weijnen has written a tool to Encode (and decode) Citrix Passwords, you can find the tool here.
  • UseLocalUserAndPassword
    • Description: Specifies whether or not to use the same user name and password the user used to log on to the client computer for authentication to the Citrix server. SSOnUserSetting must be set to On.
    • Possible values:
      Value Description
      On Use pass-through authentication.
      Off Does not use pass-through authentication (Default)
  • Username
    • Description: This parameter specifies the username for the supplied credentials.
    • Possible values: The username for the supplied credentials.
[Compress]

Contains the name of the drivers use for compression as specified in the Compress setting in the %ConnectionName% section.

Example
[Compress]
DriverName=PDCOMP.DLL
DriverNameWin16=PDCOMPW.DLL
DriverNameWin32=PDCOMPN.DLL

In the example the default drivers used for compression are specified.

Settings
  • DriverName
    • Description: This parameter specifies the name of the DOS driver file to load.
    • Possible values:
      Value Description
      PDCOMP.DLL The default driver file for used for compression (Default)
  • DriverNameWin16
    • Description: This parameter specifies the name of the Win16 driver file to load.
    • Possible values:
      Value Description
      PDCOMPW.DLL The default driver file for used for compression (Default)
  • DriverNameWin32
    • Description: This parameter specifies the name of the Win32 driver file to load.
    • Possible values:
      Value Description
      PDCOMPN.DLL The default driver file for used for compression (Default)
[Encryption]

Contains the name of the drivers use for encryption (SecureICA) as specified in the EncryptionLevelSession setting in the %ConnectionName% section. The name of the section equals the value of the EncryptionLevelSession setting.

Example 1
[Encrypt]
DriverNameWin32=PDCRYPTN.DLL
DriverNameWin16=PDCRYPTW.DLL

In the first example the default drivers used for encryption (SecureICA) are specified.

Example 2
[EncRC5-0]
DriverNameWin16=PDC0W.DLL
DriverNameWin32=PDC0N.DLL

[EncRC5-40]
DriverNameWin16=PDC40W.DLL
DriverNameWin32=PDC40N.DLL

[EncRC5-56]
DriverNameWin16=PDC56W.DLL
DriverNameWin32=PDC56N.DLL

[EncRC5-128]
DriverNameWin16=PDC128W.DLL
DriverNameWin32=PDC128N.DLL

In the second example the drivers for each encryption level (SecureICA) are specified in a separate section.

Settings
  • DriverNameWin16
    • Description: This parameter specifies the name of the Win16 driver file to load.
    • Possible values:
      Value Description
      PDCRYPTN.DLL The default driver file used for used for encryption (Default)
      PDC0W.DLL The driver file used for RC5 (128 bit – Logon Only) encryption.
      PDC40W.DLL The driver file used for RC5 (40-bit) encryption.
      PDC56W.DLL The driver file used for RC5 (56-bit) encryption.
      PDC128W.DLL The driver file used for RC5 (128 bit) encryption.
  • DriverNameWin32
    • Description: This parameter specifies the name of the Win32 driver file to load.
    • Possible values:
      Value Description
      PDCRYPTW.DLL The default driver file used for used for encryption (Default)
      PDC0N.DLL The driver file used for RC5 (128 bit – Logon Only) encryption.
      PDC40N.DLL The driver file used for RC5 (40-bit) encryption.
      PDC56N.DLL The driver file used for RC5 (56-bit) encryption.
      PDC128N.DLL The driver file used for RC5 (128 bit) encryption.

When are .ICA files used?

.ICA files are used in many applications that allow you to connect to a Citrix XenApp / XenDesktop environment. Most common used are the Citrix Web Interface and the Citrix CloudGateway, but third party applications like Denamik LoadGen use .ICA files as well. Usually the use of .ICA files is temporarily and hidden for the end user, which is a good thing.

Web portal default configuration

When you launch a published application / desktop via the web portal supplied by Citrix (WebInterface, StoreFront or VDI in a box) a default configuration is applied. You can alter the default configuration to meet your needs, if it isn’t available in the management console (most settings are not configurable via the management console). The default configuration is stored in a default.ica file.

The location of the default.ica depends on the platform you’re using and the name of the site.

Citrix-Web-Interface-Management_thumSince both WebInterface and StoreFront are integrated in Microsoft Internet Information Services (IIS) the configuration is stored in a directory in the %SystemRoot%\inetpub (default location). For each site a directory is created which you specified when you created the site.

Assuming you’ve used the default site name, these are the locations where the default configuration is stored:

Platform Version Type Location
Web Interface 5.x XenApp \inetpub\wwwroot\Citrix\XenApp\conf
4.5 / 4.6 XenApp \inetpub\wwwroot\Citrix\AccessPlatform\conf
4.0 XenApp \inetpub\wwwroot\Citrix\MetaFrame\conf
All XenApp services / PNAgent \inetpub\wwwroot\Citrix\PNAgent\conf
StoreFront All All \inetpub\wwwroot\Citrix\Store\App_Data
VDI in a box All All /home/kvm/install/servlet_container/webapps/

dt/WEB-INF/etc/proto.ica (not default.ica!)

Thanks Andrew Morgan for locating the default configuration for Storefront services and VDI in a Box.

 

 

Change specific published application / desktop

If you want to change the setting / behavior of a specific published application / desktop you need to add the published resource in the [ApplicationServers] section and add a [%ConnectionName%] section with the required settings.

It is important that the name of the connection (%ConnectionName%) is exactly as it is shown in the application set of the management console.

Example

[ApplicationServers]
Desktop - Windows 7=

[Desktop - Windows 7]
TWIMode=Off
DesiredHRES=1440
DesiredVRES=800

How can I create an .ICA file?

Well, there are a number of options:

  1. Manual
  2. Citrix ICA File Creator – CTX113472
  3. Citrix Quick Launch – CTX122536

The first option, manual, is of course an option but it’s quite some work for an easy task. Keep in mind that the Citrix Receiver (or older clients) are rather restrictive with the information it returns. If there’s an (syntax) error in the ICA file… well, in most cases you need to sort that our yourself.

The second option, the Citrix ICA File Creator, is a less time consuming option than creating it manually but is a bit clunky. It works, but it’s not the best tool (and unsupported).

The third option is the Citrix Quick Launch tool ,which is also provided by Citrix (and unsupported, btw), and is built to offer some features of the deprecated Program Neighborhood (CTX121727). IMHO this is the best way of building ICA files Not only because it offers the most features (it is recently updated) but also because you can connect and test the connection immediately!


Citrix-Quick-Launch_2012-07-25_16-51


Citrix-Quick-Launch_2012-07-25_16-52[12]Citrix-Quick-Launch_2012-07-25_16-52[3]Citrix-Quick-Launch_2012-07-25_16-52[2]Citrix-Quick-Launch_2012-07-25_16-52[13]Citrix-Quick-Launch_2012-07-25_16-52[6]Citrix-Quick-Launch_2012-07-25_16-53[2]

PS: The Citrix Quick Launch works even on desktops with 125% DPI (default with a resolution of 1920×1080 on my laptop)! So kudos to the developers who where willing to build a version that supported 125% DPI (and James Denne – @JimmyLeroux – for contacting them).

Comments

Did I miss anything or do you have a suggestion? Let me know in the comments.

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *