Advice for developers on login to XenServer and debug of connections to XenServer


You should always normally use session.login_with_password to log into a XenServer host. If you try to connect to a slave you should receive a HOST_IS_SLAVE error code, however you should also be able to parse the address of the true master from the other supplementary (error description) returned information, you can see many examples of this in C# within the XenCenter Code, such as:

            if (error is Failure)
                Failure f = (Failure)error;
                if (f.ErrorDescription[0] == Failure.HOST_IS_SLAVE)
                    string oldHost = connection.Name;
                    ((XenConnection)connection).Hostname = f.ErrorDescription[1];

The method session.slave_local_login_with_password is provided as API for use in failure situations to login to a slave when the master host has truly gone down. It should not be used to routinely login into slave hosts and the resulting sessions are only good for use on that particular host.


Best practice session management and debugging session leaks

The session limit of XenAPI process (XAPI) is 400. When the limit is exceeded, the oldest session is terminated (that is the session that has not been used the longest that is expired). The oldest session might be active and in use. When the session is terminated, the client using that session gets disconnected without notification. The session is expired, and therefore the session ID can no longer be used to make XenAPI calls. You then need to login again. This may affect you even when you don’t have a connection open at the time, because session IDs can be reuse across TCP connections. Inactive sessions are terminated after 24 hours.

Note: Clients can be any of the following: slaves in the pool, users running XenCenter, third-party applications that leverage XAPI, internal Dom0 processes, cloud management applications, distributed desktop controllers, or any systems interacting with the pool through XAPI.

A session is created when a client logs on to the server using the session.login_with_password call. The client gets a session ID to make API calls. Once an application is finished interacting with a XenServer Host it is good practice to call session.logout. This invalidates the session reference (so it cannot be used in subsequent API calls) and simultaneously de-allocates server-side memory used to store the session object.

Although inactive sessions will timeout eventually (24 hours), the server has a hardcoded limit of 400 concurrent sessions. Once this limit has been reached fresh logins will evict the oldest session objects, causing their associated session references to become invalid. It is essential that application developers ensure they release redundant sessions accessing the server. The best policy is to create a single session at start-of-day, use this throughout the applications lifetime(note that sessions can be used across multiple separate client-server network connections ) and then explicitly logout when possible. Developers should take care to handle session release during exception handling and application failure where appropriate.

More details on the consequences of leaking sessions and how to detect this is the case using XenServer logs is detailed in

An overview of sessions can also be found in Chapter 3 of the XenServer SDK guide.

Debugging Session Leaks

Many session issues are detected by Citrix's free TaaS log analysis service. In the first instance we would suggest developers who suspect a session leak follow the advice on Server Status Report collection and run the logs through the auto-analysis tool, following the advice here

Debugging Session Leaks - Example Developer Script

A script written internally by one of our developers debugging a session issues in a third party application is available on XenServer 6.1 is available as is, here. The script gives an overview of all sessions that were created but not destroyed by the caller (in the timespan covered by the logs). It also shows whether the XAPI Garbage Collection (GC) process destroyed the session or not (due to exceeding the limit of 400 sessions, or because the session was not used for 24 hours). It also shows the user name used when logging in, and whether the session was created within dom0 on a unix domain socket (UNIX) or over a TCP connection (INET). In the latter case, the user-agent it listed as well. Note that the user name in this case is not relevant for authentication, but can in some cases be used to isolate what the application that created the session was.


Connection Problems

Many connection problems can arise if Network Time Protocol (NTP) synchronisation is wrong. It can often be worth checking your host synchronisation. This forum thread provides a lot of helpful advice on how to do this.


Client side timeout

This is not something we would wish to do and we do not encourage third parties to attempt to implement such an algorithm. Some tasks can take a long time or in the case of a genuine server or network issue be temporarily blocked, if a client simply drops the connection and attempts to re-perform the original call to the server this can in fact compound issues. It is very likely that the original call is still active server-side, further repeated calls to perform the same action are likely to cause more problems rather than solve any.

Instead we recommend that developers include logic in their to launch asynchronous XAPI calls in another thread, poll the task and then call the XAPI Task.cancel function if the initial Task has definitely stalled or the server has failed, and only as a last resort cut off the connection. Some advice on asynchronous API calls and task polling can be found, here.


Commonly used ports in XenServer and other Citrix Products













About XenServer

XenServer is the leading open source virtualization platform, powered by the Xen Project hypervisor and the XAPI toolstack. It is used in the world's largest clouds and enterprises.
Commercial support for XenServer is available from Citrix.