|
Version 6.3 |
|
| ||||||||||||||||||||||
Configuring the XIMSS ModuleUse the WebAdmin Interface to configure the XIMSS module.
Open the Access page in the Settings realm:
Use the Log setting to specify the type of information the XIMSS module should put in the Server Log. Usually you should use the Major (message transfer reports) or Problems (message transfer and non-fatal errors) levels. But when you experience problems with the XIMSS module, you may want to set the Log Level setting to Low-Level or All Info: in this case protocol-level or link-level details will be recorded in the System Log as well. When the problem is solved, set the Log Level setting to its regular value, otherwise your System Log files will grow in size very quickly. The XIMSS module records in the System Log are marked with the XIMSSI tag. When you specify a non-zero value for the Maximum Number of Channels setting, the XIMSS module creates a Listener. The module starts to accept all XIMSS connections that clients establish in order to communicate with your Server. The setting is used to limit the number of simultaneous connections the XIMSS module can accept. If there are too many incoming connections open, the module will reject new connections, and the client should retry later. By default, the XIMSS module Listener accepts clear text connections on the TCP port 11024. Follow the Listener link to tune the XIMSS Listener. XIMSS Connections to Other ModulesXIMSS connections can be made to TCP ports served with other CommuniGate Pro modules. If the first symbol received on a connection made to the HTTP module is the < symbol, the HTTP module passes the connection to the XIMSS module. When a connection is passed:
When all users initiate XIMSS connections via other Module ports, you can disable the XIMSS Listener by setting all its ports to zero. Flash SecurityWhen a Flash client connects to an XMLSocket server (such as the CommuniGate Pro XIMSS module), it can send a special policy-file-request request. The XIMSS module replies with an XML document allowing the client to access any port on the Server. XIMSS SessionsWhen a user is authenticated, the XIMSS module creates a XIMSS session.
The current XIMSS module TCP connection can be used to communicate with that session.
A XIMSS session can be created without the XIMSS module, using special requests sent to the HTTP User module. See the XIMSS Protocol section for more details. The XIMSS session records in the System Log are marked with the XIMSS tag. HTTP BindingA client application can access the XIMSS interface via HTTP connections.
A client application should start by sending an HTTP Login request to create a new XIMSS session. When a XIMSS session is created, the client application can send XIMSS protocol requests to it and receive XIMSS protocol responses from the session using HTTP requests. Client applications can use GET and POST HTTP requests.
Open the HTTP User Module settings, and find the Sub-Protocols panel: The Access setting specifies who can create XIMSS sessions using HTTP Binding. HTTP LoginTo start a XIMSS session, a client application should send an HTTP request to the CommuniGate Pro HTTPU module using the following URLs:
If the userName parameter is absent, the Server tries to authenticate the request using
the TLS Client Certificate (if specified), or using the HTTP authentication methods.
A request to the /ximsslogin/ URL can contain a text/xml body. In this case, no login operation is performed.
C:GET /ximsslogin/ HTTP/1.1
Host: myserver.com Content-Type: text/xml Content-Length: 42 <XIMSS><listFeatures id="list" /><XIMSS> S:HTTP/1.1 200 OK Content-Length: 231 Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS><<features id="s" domain="x.domain.dom"><starttls/><sasl>LOGIN</sasl><sasl>PLAIN</sasl><sasl>CRAM-MD5</sasl><sasl>DIGEST-MD5</sasl><sasl>GSSAPI</sasl><nonce>2C3E575E5498CE63574D40F18D00C873</nonce><language>german</language><signup/></features><response id="s"/></XIMSS> If the user has been successfully authenticated, and the XIMSS session has been created, the HTTP Login response contains the XIMSS session message with the session ID string. Note that the session message does not contain the id attribute. Example:
C:GET /ximsslogin/?userName=account@domain&password=abcd&version=6.1 HTTP/1.1
Alternative URLs can be used to start a XIMSS session using the TLS Client Certificate,
or using the HTTP authentication methods:
Host: myserver.com Content-Length: 0 S:HTTP/1.1 200 OK Content-Length: 105 Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS><session urlID="562-kAI2lxNBR4ApmHg4wiW9" userName="account@domain" realName="J. Smith" version="6.1.2" /></XIMSS>
This method is useful if an application first retrieves an HTML page or some other document using the /auth/ realm, forcing the browser to ask the user for credentials, and then the application creates a XIMSS session for the same user, as the browser will resend the same credentials when sending a request to the /auth/ximsslogin/ URL. HTTP Synchronous CommunicationsA client should send requests to a created XIMSS session use the following Session URL:
The HTTP request body should contain one <XIMSS /> element, with zero, one, or more XIMSS protocol requests. The Server returns one <XIMSS /> element in the HTTP response body. This element contains the XIMSS protocol response messages (one for each XIMSS request sent, in the same order), and all synchronous data messages generated with the submitted XIMSS requests. Example:
C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/sync HTTP/1.1
Host: myserver.com Content-Length: nnn <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS> S:HTTP/1.1 200 OK Content-Length: nnn Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS><response id="i1"/><currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/><response id="i2"/></XIMSS> If a XIMSS client works in an unreliable environment, where it may have to resend HTTP requests, then
each non-empty HTTP request should contain a reqSeq parameter. This parameter value should be increased by 1 for each new HTTP request sent.
A client application can use an "empty request" (an HTTP request without a body) to read asynchronous XIMSS data messages. When such an empty request is received, the Server checks if there is any pending asynchronous data messages for the specified session. If there is no pending asynchronous data messages, the request is held until either:
An empty request can specify the waiting time as the maxWait parameter (number of seconds). If no data messages were retrieved, the Server sends a response containing an empty <XIMSS/> element, without any attributes. If some data messages were retrieved, the Server sends a response (an "asynchronous response") containing one <XIMSS/> element, with the respSeq attribute. This attribute contains the sequence number for this <XIMSS/> response element. For each session, the Server keeps the last "asynchronous response" composed. Each empty request should contain a ackSeq parameter. It should contain the respSeq value of the last received asynchronous response.
When the Server receives an empty request with the ackSeq equal to the respSeq value of the kept last composed asynchronous response, it considers that response as "acknowledged", and removes it. When the Server receives an empty request with the ackSeq equal to the respSeq value of the last composed asynchronous response minus one (respSeq-1), and it still keeps this composed response, the Server resends that response to the client. As a result, if the client encounters any communication error while doing an "empty request" HTTP transaction, it can resend that empty request. An empty request without an ackSeq parameter acknowledges all "asynchronous responses" composed and kept. When a server returns an empty <XIMSS/> element, the next empty request can contain either no ackSeq parameter, or the same
ackSeq parameter as the previous empty request. Because of this subsequent empty requests may use the same request URL and the same parameters,
and the client platform may return the previous cached <XIMSS/> element result immediately, without sending the request to the server.
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&reqSeq=0 HTTP/1.1
Host: myserver.com Content-Length: 0 ...optional pause (up to 90 seconds)... S:HTTP/1.1 200 OK Content-Length: 10 Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS/> C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&reqSeq=1 HTTP/1.1 Host: myserver.com Content-Length: 0 ...optional pause (up to 90 seconds)... S:HTTP/1.1 200 OK Content-Length: nnn Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS respSeq="1"><folderReport folder="INBOX" mode="notify" /></XIMSS> response did not reach the client, client is resending the request C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&reqSeq=1 HTTP/1.1 Host: myserver.com Content-Length: 0 S:HTTP/1.1 200 OK Content-Length: nnn Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS respSeq="1"><folderReport folder="INBOX" mode="notify" /></XIMSS> C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=1&reqSeq=2 HTTP/1.1 Host: myserver.com Content-Length: 0 ...optional pause (up to 90 seconds)... S:HTTP/1.1 200 OK Content-Length: 10 Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS/> HTTP Asynchronous CommunicationsA client can send requests to a created XIMSS session so that all responses (including the response messages and synchronous data messages) are returned only in response to the "empty requests".
The HTTP request body should contain one <XIMSS /> element, with zero, one, or more XIMSS protocol requests. All generated response messages (one for each XIMSS request sent, in the same order), and all synchronous data messages generated with the submitted XIMSS requests are re-submitted to the XIMSS session as asynchronous messages. The Server returns an empty HTTP response. Example (single connection, polling):
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=0&ackSeq=0&reqSeq=0 HTTP/1.1
Example (2 connections, waiting):
Host: myserver.com Content-Length: 0 S:HTTP/1.1 200 OK Content-Length: 10 Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS/> C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/async HTTP/1.1 Host: myserver.com Content-Length: nnn <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS> S:HTTP/1.1 200 OK Content-Length: 0 Connection: keep-alive Content-Type: text/plain;charset=utf-8 Server: CommuniGatePro/5.3 C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=0&ackSeq=0&reqSeq=1 HTTP/1.1 Host: myserver.com Content-Length: 0 S:HTTP/1.1 200 OK Content-Length: nnn Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS respSeq="1"><response id="i1"/><currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/><response id="i2"/></XIMSS>
Monitoring XIMSS ActivityYou can monitor the XIMSS Module activity using the WebAdmin Interface. Click the Access link in the Monitors realm to open the Access Monitoring page:
XIMSS activity can be monitored with the CommuniGate Pro Statistic Elements. |