Understanding Citrix XML Broker and troubleshooting one XML broker issue

Understanding Citrix XML broker
Let’s start with the broad definitions:

Q. What is XML?
A. XML is a markup language for documents containing structured information

Q. What is a markup language?
A. A markup language is a mechanism to identify structures in a document. The XML specification defines a standard way to add markup to documents.
Structured information contains both content (words, pictures, etc.) and some indication of what role that content plays (for example, content in a section heading has a different meaning from content in a footnote, which means something different than content in a figure caption or content in a database table, etc.). Almost all documents have some structure.
XML was created so that richly structured documents could be used over the web

Q. What is a broker?
A. A broker is an individual or party (brokerage firm) that arranges transactions between a buyer and a seller, and gets a commission when the deal is executed.

Citrix Analogy:
Q. What is a Citrix XML broker?
A. A Citrix XML broker (a Windows server with Citrix XenApp software installed) that arranges transactions between the Web Interface (buyer/client/) and the Zone Data collector (seller/server).

Up to Xen App 6.0, any XenApp server could be an XML broker on a XenApp farm. All you needed to do was installing the Web Interface Console onto a separate server and pointing it to whichever XenApp server(s) in your farm you wanted to nominate as XML brokers.

With XenApp 6.5 only servers that are controllers can be XML brokers, so the previous paragraph won’t apply here
XenApp 6.5 offers new roles, including a worker role and a controller role. The default role for a XenApp server is a controller role. The controller server is responsible for farm management tasks while the only task of the session-only servers or workers is to host user sessions and publish apps.

A farm requires at least one server to act as a controller, which can host the XML and Zone Data Collector roles. A worker cannot perform the role of a data collector, nor can it trigger elections.

By default the server that contains the Web Interface Console is not an xml broker unless you install XenApp and Web Interface console on the same server.

The Web Interface (usually on a client computer) communicates directly with the XML broker (a Windows Server installed with Citrix XenApp Server). The communication consists of a series of requests from the Web interface and responses from the XML broker, as mentioned in the following list:

1. RequestCapabilities – from the Web Interface
2. ResponseCapabilities – from the XML broker
3. RequestValidateCredentials – from the Web Interface
4. ResponseValidateCredentials – from the XML broker
5. RequestAppData – from the Web Interface
6. ResponseAppData – from the XML broker
7. RequestAppData – from the Web Interface
8. ResponseAppData – from the XML broker
9. RequestReconnectSessionData – from the Web Interface
10. ResponseReconnectSessionData – from the XML broker

After the Step 8, ResponseAppData, of the preceding list, the log in and enumeration is complete. The Step 9, RequestReconnectSessionData, and Step 10, ResponseReconnectSessionData, are optional based on the configuration of the Web Interface.

To better understand the big picture of how XML brokers fit in the logon process, here is a high level video diagram of the logon process, from the moment an end user hits the WebInterface server (via the end user’s Web browser), and STA/XML/ZDC connections up to the point the session is launched.

Why you should be using the latest version of the Web Interface (currently 5.4 as of February, 2012):

Prior to Web Interface version 5.1.1, when multiple XML brokers are configured, if any XML broker is able to respond over the network but unable to process requests from Web Interface, the Web Interface server simply waits for a response until it times out rather than failing over to the next XML broker configured on the site. The most common reason for the XML service to become unresponsive is because it is busy waiting for a response from the IMA service. Therefore, if IMA is hung or unresponsive on the XML broker or the Farm Master, it impacts the XML service’s ability to respond to Web Interface in a timely manner. Active Directory and DNS issues have been known to cause these problems with the IMA service.

The end result is that new users logging on to Web Interface do not receive a list of applications for any farm and the Web Interface session times out (after approximately two minutes) with the error shown below:

The web site is experiencing technical difficulties. We apologize for any inconvenience.
The internal error might be only temporary. Try reconnecting, if the problem persists, contact your system administrator

(from CitrixE-docs)
Citrix XML Service and the Citrix XML Broker
The Citrix XML Broker functions as an intermediary between the other servers in the farm and the Web Interface. When a user authenticates to the Web Interface, the XML Broker:

Receives the user’s credentials from the Web Interface and queries the server farm for a list of published applications that the user has permission to access. The XML Broker retrieves this application set from the Independent Management Architecture (IMA) system and returns it to the Web Interface.
Upon receiving the user’s request to launch an application, the broker locates the servers in the farm that host this application and identifies which of these is the optimal server to service this connection based on several factors. The XML Broker returns the address of this server to the Web Interface.

The XML Broker is a function of the Citrix XML Service. By default, the XML Service is installed on every server during XenApp Setup. However, only the XML Service on the server specified in the Web Interface functions as the broker. (The XML Service on other farm servers is still running but is not used for servicing end-user connections.) In a small farm, the XML Broker is typically designated on a server dedicated to several infrastructure functions. In a large farm, the XML Broker might be configured on one or more dedicated servers.
The XML Broker is sometimes referred to as a Citrix XML Server or the Citrix XML Service. For clarity, the term XML Broker is used to refer to when the XML Service functions as the intermediary between the Web Interface and the IMA service, regardless of whether it is hosted on a dedicated server or collocated with other infrastructure functions.

There are many symptoms associated with XML broker issues. I will write another article on the most common ones, but here is an example of one:

Applications take a long time to enumerate at the Web interface on the client side (usually a minute or more):
These are the things you should be checking and trying as troubleshooting:
1. Recreate the LHC (Local Host Cache) on the XML brokers and on the ZDC (Zone Data Collector) (to recreate the LHC, you can issue three commands on a CMD prompt:
a) net stop imaservice b) dsmaint recreatelhc ; c) net start imaservice
2. If you use SSL ,enable socket pooling on the Web Interface console (at the WI console choose Server Farms. Advanced and check the socket pooling box)
If you don’t use SSL, disable socket pooling (SP). A socket may get corrupted and when you use SP on a HTTP site and there is corruption you will get connection and delay issues n the Web Interface. Disabling SP will force the connection to create a new socket each time a connection is made, which is fine. (this CTX article explains Socket Pooling beautifully!)
3. If the authentication method is Passthrough, change it to Explicit and test if the the enumeration takes as long
4. Create a new site on the WI server (Web site or PNA Agent site) and try different authentication methods. This is a quick and easy way of testing if there is a corruption on the other Websites that you are using (Check Event viewer when you attempt the connection with the new web site and see if the same errors occur)

I will be discussing more XML issues on future posts.

Source for some of the information provided in this post:

Citrix E-Docs
XML by O’Reilly

Another good definition:
by Peter David
The XML Broker is the ‘point of contact’ in your presentation server farm used by Web Interface to autheticate users and enumerate applications.

When you enter your credentials, they are passed to the XML broker configured in Web Interface Admin, which then passes them on to the IMA service, which ultimately fulfills the authentication request.

Once authenticated, the XML service also talks to the data collector and various servers (via XML or IMA) to get application information, and to send the user to the least busy server providing the application the user requested.

Several of these ‘brokers’ can be configured in Web Interface Admin for failover or to load balance the XML requests from Web Interface.

Last update November 28, 2012


15 Responses to “Understanding Citrix XML Broker and troubleshooting one XML broker issue”

  1. Arun PC Says:

    Hello Apttech(since i don’t know your name),

    I should acknowledge you for writing such a great blog. The content is awesome, succinct and deep.

    This blog is a blessing for someone who wants to get his hands dirty.

    Keep up the great job!


  2. harsh tomar Says:

    this is really good

  3. kranthi Says:

    very nice blog, usefull information

  4. Asrar Says:

    Very nicely written…. Could you please clarify more on this:
    “When you enter your credentials, they are passed to the XML broker configured in Web Interface Admin, which then passes them on to the IMA service, which ultimately fulfills the authentication request.”

    How does IMA service talk to Active Directory… >> this is what I want to understand

  5. Koushik Says:

    Perfect Article for starters!!

  6. Richard Ndiomo Says:


    Very interresting your paper.
    I see that you are an expert for the deployement of Citrix.

    Can you help me to have the traffic flow to the design that follow.

    Acees Gateway ( SSSL VPN), Netscaler (as a load balancer and web interface), Netapp 6.1, Pasword manager, Active directory or Raduis server for authentication.

    How is traffic flow of the user looking to an information in a server farm published by Netapp?

    The design is:

    Internet->AG->Netscaler -> Citrix farm.

    • apttech Says:

      Sorry. I don’t provide technical support help on this blog; Also this question should be answered by the Netscaler group at Citrix Good luck!

  7. Ramesh Patel Says:

    Very Nice blog, after reading this i hav ecleared my doubt abt XML broker.


  8. Kartheek Says:


  9. Amar Honnungar Says:

    Good article…..

  10. ARINDAM Says:

    I have a problem with my new XenApp 5 Farm. I have 5 zones in my farm based on their location. When users from one zone is trying to launch any application, it is pointing to our main zone’s citrix servers, not to the regional citrix server (example, users from singapore is getting connected to Xenapp servers at USA, not their local servers). I have zone preference policy configured based on client IP Address range to point to their primary regional zone.

    Please help me on this issue.


    • apttech Says:

      Sorry, I don’t provide support on this blog; just a couple hints though: When you make configuration changes it is always good to recreate the Local Host cache on the ZDC and on the member servers (after stopping the IMA service go to a CLI command prompt and type: dsmaint recreatelhc then start the ima service); Also if it was policy change remember to issue gpupdate /force on the server(s) you made the change. Also when you publish apps you can specify the servers in which the users will launch the apps from; For the Singapore users make sure to publish the apps on the servers located in the Asia zone; You could create a AD security group for the Singapore users and when you publish the apps on the Asia zone, pick the security group you created for the Singapore users. Good luck!

  11. Danny Says:

    Great Blog. It answered so many of my xml broker questions.Thank-you

  12. DC Says:

    Nice work

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: