CONNECT

Client requests a connection to a Broker


After a TCP/IP socket connection has been established between the client and the broker, a protocol level session must be established.
It is anticipated that the direction of connection will be client to broker, and that the client would not typically support broker listener functionality.
 
 

Fixed Header

See the Fixed Header section for more information,
 
bit
7
6
5
4
3
2
1
0
byte 1 
Message Type (1)
DUP flag
QoS level
RETAIN
 
0
0
0
1
x
x
x
x
byte 2 
Remaining Length

The DUP, QoS and RETAIN flags are not used in the CONNECT message.

The Remaining Length is the length of the Variable Header (12 bytes), plus the length of the Payload.
This may be a multi-byte field. See the Fixed Header section for more details.
 

Variable Header

The CONNECT messsage carries Variable Header data comprising: See the Variable Header section for more information.
 

TNCOMP flag

Note that for this version of the protocol, Topic Name Compression is not available, and so the value of this flag is always 0.
 

Clean Start flag

The Clean Start flag provides a way for the client to go back to a known, "clean" state with the broker. If the flag is set, the broker will discard any outstanding messages for that client, delete all subscriptions for that client, and reset the Message ID to 1. The client will then be able to proceed without the risk of any data from previous connections interfering with the current connection.
 

"Will" message flags

The "Will" message is a mechanism by which a client can define a message to be published on its behalf by the broker, in the event of the client's "death". We define "death" in this context to mean that either an I/O error is encountered by the broker during communication with the client, or the client fails to communicate within the Keep Alive Timer schedule (see below). The receipt of a DISCONNECT packet from the client does NOT trigger the sending of the Will message.

The fields associated with the Will message are:

Keep Alive Timer

The Keep Alive timer is measured in seconds, and tells the broker the maximum time interval between receiving messages from this client. This gives the broker a way of detecting that the network connection to a client has dropped, without having to wait for the long TCP/IP timeout. It is the responsibility of the client to ensure that it sends some kind of message within each Keep Alive time period. If there is not going to be a data-related message within the time period, then the client should send a PINGREQ message, which will be acknowledged by the broker with a PINGRESP.

If the broker does not hear from this client within 1.5 times the Keep Alive time period (i.e. the client is allowed half a time period's "grace"), it performs the disconnection processing that it would have done if the client had sent a DISCONNECT message. Note that this does not impact any of the client's subscriptions. See the DISCONNECT section for more details.

The Keep Alive timer is a 16-bit value representing the number of seconds for the timeout. This allows timeouts up to around 18 hours.  The appropriate timeout value is applicatoin specific, but it is anticipated  that timeouts would be of the order of a few minutes.
A Keep Alive time of 0 indicates that there will be no Keep Alive timeout processing, i.e. the broker will not disconnect a client due to elapsed time.
The ordering of the 2 bytes of the Keep Alive timer is MSB, then LSB (big-endian).
 
 
 

Example

In this example, the Clean Start flag is set (1),  the TNCOMP flag is clear (0), and the Keep Alive timer is set to 10 seconds (0x000A).
A "Will" message is being defined (Will Flag is set (1)), and the Will message is to be sent at QoS 1 (Will QoS is 1) , but not RETAINed (Will RETAIN is clear (0)).
 
 
  Description
7
6
5
4
3
2
1
0
Protocol Name
byte 1 Length MSB (0)
0
0
0
0
0
0
0
0
byte 2 Length LSB (6)
0
0
0
0
0
1
1
0
byte 3
'M'
0
1
0
0
1
1
0
1
byte 4
'Q'
0
1
1
1
0
0
0
1
byte 5
'I'
0
1
1
0
1
0
0
1
byte 6
'p'
0
1
1
1
0
0
0
0
byte 7
'd'
0
1
1
0
0
1
0
0
byte 8
'p'
0
1
1
1
0
0
0
0
Protocol Version Number
byte 9 Version (2)
0
0
0
0
0
0
1
0
Connect Flags
byte 10 Will RETAIN (0)
Will QoS (01)
Will flag (1)
Clean Start (1)
TNCOMP Req (0)
x
x
0
0
1
1
1
0
Keep Alive timer
byte 11 Keep Alive MSB (0) 0 0 0 0 0 0 0 0
byte 12 Keep Alive LSB (10) 0 0 0 0 1 0 1 0

 

Payload

The Payload section of the CONNECT message contains either one or three UTF-encoded  strings. The first is the Client Identifier, between 1 and 23 characters long, which uniquely identifies the client to the broker. Care should be taken in the selection of this identifier, as it must be unique across all clients connecting to a single broker. The Client Identifier is used as a key in the handling of Message Identifiers for messages with QoS 1 and QoS 2. See the QoS section for more details.

NOTE: The Client Identifier must not be more than 23 characters. The broker will  reject a CONNECT request with a client identifier that is not 1-23 characters long, with a CONNACK return code of 2: Identifer Rejected.

The existence of the second and third UTF-encoded strings depends on the setting of the "Will" flag in the Connect Flags byte of the Variable header. If the Will Flag is set, then the payload must contain a total of three UTF-encoded strings.

The second string is called "Will Topic", and is the topic name to which the "Will Message" (see below) will be published (at a QoS defined by the Will QoS field, and RETAIN status defined by the Will RETAIN flag, both in the Variable Header.)

The third UTF-encoded string is called "Will Message", and defines the content of the message which will be published (on the Will Topic topic) if the client is unexpectedly disconnected.
NOTE that although the Will Message is UTF-encoded here in the CONNECT message, when it is published to the Will Topic, only the actual bytes of the message are sent as the content, NOT the first two length bytes.
That is, the message which is sent out upon execution of the Will by the broker is not UTF-encoded, but "raw" ASCII.
 

See the UTF section for more information about UTF-encoding.
 
 
 
 

Response

The response from the broker to a client CONNECT messsage is a CONNACK message.

NOTE: if a CONNACK is not received from the broker within a "reasonable" amount of time, the client should close the TCP/IP socket connection and start the session again: open a socket to the broker and issue a CONNECT message. What constitutes a reasonable amount of time will be governed by the nature of the application, and the communications infrastructure being used.
 
 

Discussion

ASC on the encoding of the Will Message
Jonathan pointed out that the Will Message should strictly be a "BLOB", rather than a UTF-encoded string. However, we don't have a way (yet) in the protocol of defining a BLOB of some specified size, so for now we will use UTF-encoding, and put the "content" part of the UTF-encoded string into the Payload of the message when the Will is PUBLISHED.
This may be revisited in the future, but I think it's OK for what we want to do with it at the moment.
ASC on the "Will" message
The idea of a Will Message came after discussions about how to implement Instant Messaging using the pub/sub paradigm. It was reallised that if a client is involuntarily disconnected, then the only entity that knows that the client has gone of line is the broker: there is no way for other clients to learn of the disconnection. So the Will message gives a way for the client to register with the broker a message which is to be published on a specified topic in the event of the client's untimely death, which would mean either failing to check in on time under the Keep Alive regime, or if a socket error occurs when the broker attempts to send a message to the client.
ASC on Authentication
Authentication, with exchange of certificates, etc, belongs in the CONNECT message, but is not there yet.

 
ASC on Client Identifier length
The 23 character limitation arises because we currently use the MQ Series "Correl ID" field to uniquely identify the client inside the broker. This field has a limit of 23 characters. The proposal for tighter integration of the MQIpdp into MQ Series Integrator Version 2.0 would provide an upper limit of 48 characters. But it stays at 23 for now.

 
AN on Version field
It should be noted that implementations of newer version of the protocol should strive to maintain backwards compatability with older version of the protocol if at all possible. It was our experience with the Ambrosia product that on every version change, regardless of the impact on the field equipment, all field equipment had to be updated immediately in order to maintain a working connection. When faced with the logistics of updating hundreds of field devices with newer versions of the implementation, customers would favor a backwards compatable migration.
ASC comment
The protocol Version field has been moved out of the message header, and into the CONNECT message, as in a connection-orientated environment like TCP/IP, there is always the "wrapper" of the session set up and tear-down to pass over version information. It would be perverse to attempt to change versions mid-session.
ASC on Version field
Preferably, the Version number will be moved to the CONNECT message. However, if for some reason it is decided to bring it back into the Fixed Header at some point in the future (for example, if a connectionless network protocol such as UDP becomes ubiquitous), then it could probably be reduced in size, maybe to 4 bits from 8, giving 16 values before cycling, rather than 256.
Comment
The Version field will be in the CONNECT message.

 
AN on sessions
Once a connection has been established between the client and broker, Publish and Subscribe messages can proceed for the duration of a valid network socket connection.
BACK to index 
Last Modified: 22-October-99