Connecting to XenApp server through command-line

Citrix Admins out there probably know the issue; a user reports a problem and you need to troubleshoot the problem on the specific server that this user was logged on to. Logging on with user credentials to a certain server is not that easy, unless you create/modify a published desktop (or published application for that matter).

I created a little tool which allows you to easily connect to a published resource on a specific server. You can download it from the Tools section of my site and it’s called ICA Connect.

This tool was created to be used with Login VSI, this tool may therefore not be used with other benchmarking or loadtesting tools than Login VSI.

Using it in your Citrix environment for troubleshooting or to allow end-users to use it is allowed.

ICA Connect uses the locally installed ICA Client to create the connection, so be sure that you have installed a valid client. I actually tested it only with Citrix Receiver 3.1, but I think it should work with ICA Client 10 and up. Another prerequisite is to have .Net Framework 2.0 installed.


To get the complete list of options, use:

ICAConnect.exe /?

This will output the following:

ICAConnect v0.9 (c) 2012 Login Consultants
Created by: Floris van der Ploeg
ICAConnect /server SERVER [/application PublishedAppName] /user Username /password Password [/domain DomainName] [/color 16|256|16bit|24bit] [/resolution 1024x768] [/uselb] [/lbtype tcp|http] [/xendesktop] 

/server Server XenApp server to connect to; if the /uselb switch is set, this server is used to do load-balancing.
/user Username Username to use when connecting to the XenApp server.
/password Password Password to use when connecting to the XenApp server.
/domain Domain Domain to use when connecting to the XenApp server.
/application AppName Published application name (not display name) to connect to. If this option is not set, the connection will be made to the server's desktop
/color ColorDepth Color depth to use in ICA session; possible values are 16, 256, 16bit or 24bit.
/resolution 800x600 Resolution to use in ICA session; the width and height values are split by the "x" character.
/uselb Use load balancing instead of making a connection directly to the server defined in the /server option
/lbtype Type Browser type to use when connecting; possible values are TCP or HTTP. This option is only used when the /uselb option is used.
/xendesktop Use the ICA client integrated XenDesktop viewer. This option is only valid for older ICA Clients.

The Server, User and Password arguments are mandatory.

Connecting to a specific server

To connect to a specific server, use the following command:

ICAConnect.exe /server XASRV001 /User TestUser1 /Password MyPassword /Domain LAB

This will connect to server XASRV001 with user TestUser1 in domain LAB. It will connect to the server’s desktop, it could be that you have to define a Citrix Policy allowing connections to the server desktop. You can also define a published application or published desktop name:

ICAConnect.exe /server XASRV001 /application MyPublishedApp /User TestUser1 /Password MyPassword /Domain LAB

This allows you to connect to the published application named “MyPublishedApp” on server XASRV001. So the connection will bypass Citrix loadbalancing and connect directly to the server.

Load Balancing

To use the loadbalancing functionality of Citrix itself, use the following command:

ICAConnect.exe /server XASRV001 /application MyPublishedApp /UseLB /User TestUser1 /Password MyPassword /Domain LAB

This uses a connection to XASRV001 to make the ICA connection to published application named “MyPublishedApp”. With this connection, the defined load evaluators will be in effect and the ICA connection is made to the server with the least load.

By default (if not defined), the load balancing method is HTTP. If TCP is used in your environment, you can define this in the commandline:

ICAConnect.exe /server XASRV001 /application MyPublishedApp /UseLB /LBType TCP /User TestUser1 /Password MyPassword /Domain LAB

Modifying appearance

Using this tool, you can also define the resolution and colordepth. Valid colordepth options are as follows:

  • 16
  • 256
  • 16bit
  • 24bit

The color depth is defined by the “/color Depth” switch:

ICAConnect.exe /Server XASRV001 /Color 16bit /User TestUser1 /Password MyPassword /Domain LAB

This will use 16bit color depth in the connection. The screen resolution can be used by defining the “/resolution WidthXHeight“. The resolution size is split by the “x” character. For example: the 800 by 600 screen size is defined by “800×600”:

ICAConnect.exe /Server XASRV001 /Resolution 800x600 /Color 16bit /User TestUser1 /Password MyPassword /Domain LAB

It probably goes without saying, but all the command line options can be defined.

More information

If you need more information about this commandline tool, feel free to leave a comment or contact me via email.


I’ve  updated the version of ICAConnect, the /xendesktop option has been removed (since it actually didn’t make any difference) and I’ve added the following options:

  • /encryption EncType
  • /silent

The /encryption parameter allows you to define  the session encryption. Valid values are as follows:

  • Basic (basic encryption)
  • RC5-Logon (RC5-128bit for logon process only)
  • RC5-40 (RC5-40bit)
  • RC5-56 (RC5-56bit)
  • RC5-128 (RC5-128bit)

The /silent switch allows you to suppress all messages at the console. So, connecting to server XASRV001, with RC5-128bit encryption in silent mode would be done as follows:

ICAConnect.exe /Server XASRV001 /Encryption RC5-128 /Silent /User TestUser1 /Password MyPassword /Domain LAB

15 thoughts to “Connecting to XenApp server through command-line”

  1. HI, This is one of the great tool to be used along with Login VSI. I faced an issue when using it. It always connect through Basic Encryption. Is there any way we can configure to connect using 128-bit (RC-5) Encryption method. I dont see any switches to specify this.

    1. Thanks. Encryption is not built-in at this moment. I will build this functionality in and let you know when it’s updated.

      1. That was quick. thanks for that. By default which encryption method it connect. when i tested it always go through “Basic”.

    2. I’ve updated the tool, it now can handle encryption levels. But I believe that you (or one of your colleagues) already received the tool from one of my colleages. 🙂

  2. Hi,

    I believe this tool i used in LoginVSI to connect to XenApp and launch sessions.
    Today It was not able to connect to my XenApp server.

    To cross check I used web browser to access published desktop and I was successful in that.
    Can you help me to check if there is some issue with icaconnect binary that is used by LoginVSI.

    Do you have some issue triaging steps ?

    Error Pop up says,
    cannot connect to the Citrix Xenapp server.Protocol Driver error

    1. Hi, it is indeed the same tool in Login VSI. Protocol Driver error usually means that the ICA client cannot communicate with the XenApp server. Can you let me know what command line you’re using?

    1. Hi Aaron,

      XenDesktop is a bit more difficult, since you need to take in account the fact that the machines need to be powered on, etc. I did create a command line tool to work with StoreFront, so this works both with XenApp and XenDesktop. The problem here is that you still need a StoreFront server. Another “problem” is that this command line tool is only available in the Login VSI benchmarking tool (so I can’t make it available as download).

      I could think of re-writing the code in my own time.

      kind regards,

      1. Thanks for responding. My client is trying to migrate everyone to a new XA v7 (Xendesktop) environment and has a script that runs which checks if the user is in the migrated group and then launches an ica session. Problem is you can’t do ica files anymore, as the DDC (or StoreFront) has to be involved.

        This seems like a bigger overall issue, what about is someone has a custom coded app that launches an app as a session as part of the local app, how would they go about doing it now?

  3. Hi,

    It is a great tool, i used it directly in commnand prompt to launch sessions, which works perfectly. Is there a way to encrypt the password instead of providing plain text ?

    1. Hi Shiva,

      thanks for your comment. At this moment, the tool does not use encrpytion for the password. I could add this to the tool if you want, but I will not have time to do it any time soon. You could use some encryption/decryption command line tool to do the encrpytion part for you.

  4. Hi! Great tool….
    We have some Xen App 6 servers that randomly get that protocol driver error and then they have to be restarted to get back online. I’ve been looking for a scriptable way (hopefully in windows batch file-type environment) to test if a server is accepting connections. We use ICA files to launch applications.
    Would your script work for something like this? Does it return an errorlevel or similar output to the console if there is an connection error?

    Thanks much for any info!!


    1. Hi Matt,

      well… it has been a long while since I created this tool, so I don’t really remember if it returns an errorlevel. I do remember that it generates an error in the console. I will check if I still have the source and possibly update it.

      kind regards,

    2. Just checked…

      It does return error levels:
      Logon failed = %ERRORLEVEL% = 1
      Connection failed = %ERRORLEVEL% = 2 (protocol driver error)
      All OK = %ERRORLEVEL% = 0

  5. Hi Floris great tool, but every time i try and use it i get error connection failed to server, basically all i need to do is the ability to launch an app from citrix via command line, we have xenapp server6.5 and using receiver 4.4

Leave a Reply

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

Complete the following sum: * Time limit is exhausted. Please reload CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.