The ZeroMQ Message Transport Protocol (ZMTP) is a transport layer protocol for exchanging messages between two peers over a connected transport layer such as TCP. This document describes ZMTP/1.1.
- Name: rfc.zeromq.org/spec:15/ZMTP
- Editor: Pieter Hintjens <moc.xitami|hp#moc.xitami|hp>
- State: draft
License
Copyright (c) 2009-2011 iMatix Corporation
This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.
Change Process
This Specification is a free and open standard[2] and is governed by the Digital Standards Organization's Consensus-Oriented Specification System (COSS)[3].
Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119[1].
Goals
The ZeroMQ Message Transport Protocol (ZMTP) is a transport layer protocol for exchanging messages between two peers over a connected transport layer such as TCP. This document describes ZMTP/1.1.
In theory, ZMTP should allow full interoperability between products that implement it. However, parts of the necessary semantics are defined only in libzmq's code. We hope that over time these semantics will be properly extracted, abstracted, documented, and proven by independent code.
The primary goal of this specification is to allow interoperability between independent stacks and the libzmq stack. A secondary goal is to act as a container and catalyst for this standardization process.
Architecture
ZMTP consists of these layers:
- A framing layer that imposes a size-prefixed regularity on the underlying transport.
- A connection layer that allows two peers to exchange messages.
The Framing Layer
Preamble
The framing layer underlies everything in ZMTP. The basic transport layer (e.g. provided by TCP) is a stream. ZMTP's framing layer turns that into a series of frames, in either direction. Frames are length-specified, so that peers can safely reject frames that are oversized. ZMTP's framing design is optimized for bandwidth and performance.
Framing is used to create structured messages, rather than to break large messages into fragments. ZMTP assumes that peers will read and process all frames of a message, or none at all. Framing is particularly used to separate message content from message address envelopes (see the Content Layer).
There are two types of frames; label and data frames. Label frames are used to tag messages, providing addressing and other information. Data frames carry information between applications.
The framing layer is consistent no matter what work is happening on the connection. That is, it can be fully interpreted from the information sent on the wire.
Specification
A ZMTP message consists of 1 or more frames.
A ZMTP frame consists of a length, followed by a flags field and a frame body of (length - 1) octets. Note: the length includes the flags field, so an empty frame has a length of 1.
For frames with a length of 1 to 254 octets, the length SHALL BE encoded as a single octet. The minimum valid length of a frame is 1 octet, thus a length of 0 is invalid and such frames SHOULD be discarded silently.
For frames with lengths of 255 and greater, the length SHALL BE encoded as a single octet with the value 255, followed by the length encoded as a 64-bit unsigned integer in network byte order.
The flags field consists of a single octet containing various control flags. Bit 0 is the least significant bit.
- Bit 0 (MORE): More frames to follow. A value of 0 indicates that there are no more frames to follow. A value of 1 indicates that more frames will follow. On messages consisting of a single frame the MORE flag MUST be 0.
- Bits 1-6: Reserved. Bits 1-7 are reserved for future use and MUST be zero.
- Bit 7 (LABEL): Label frame. A value of 1 indicates that this is a label frame. Label frames provide information about the message, and are not delivered to applications.
The following diagram shows the layout of a frame with a length of 1 to 254 octets:
+----------------+
Octet 0 | Length |
+----------------+
Octet 1 | Flags |
+----------------+- ... ---------------------+
Octets 2+ | Body Length - 1 octets |
+------------------ ... ---------------------+
The following diagram shows the layout of a frame with length of 255 or more octets:
+----------------+
Octet 0 | 0xff |
+----------------+- ... ---------------------+
Octets 1-8 | Length 8 octets |
+------------------ ... ---------------------+
Octet 9 | Flags |
+----------------+- ... ---------------------+
Octets 10+ | Body Length - 1 octets |
+------------------ ... ---------------------+
The Connection Layer
Preamble
The connection layer provides a way for peers to identify each other at TCP connection time. A ZMTP connection is equivalent to a TCP connection. If peers disconnect and reconnect, this acts as two separate ZMTP connections.
Specification
A ZMTP connection is bidirectional and asynchronous. That is, either peer MAY send a message to the other peer at any time.
Each side of the connection consists of a greeting followed by zero or more messages.
A peer SHALL send a greeting consisting of a challenge frame, and either an anonymous frame or an identity frame. An anonymous frame consists of an empty string. This tells the other peer that the connection has no durability, and all resources associated with it can be deleted when the connection ends. An identity frame consists of a unique string of 1 to 255 octets. This tells the other peer to associate resources with that identity, and hold them indefinitely when the connection ends.
Full ZMTP Grammar
The following ABNF grammar defines the full ZMTP protocol:
zmtp = *connection
connection = greeting *message
greeting = challenge anonymous / identity
challenge = %x04 %x00 version socket-type more
version = %x11
socket-type = OCTET
anonymous = %x01 final
identity = length final (%x01-ff) *OCTET
message = *more-frame final-frame
more-frame = length more body
final-frame = length final body
length = OCTET / (%xFF 8OCTET)
more = %x01
final = %x00
body = *OCTET
Backwards Compatibility
Applications can detect ZMTP/1.0[4] (which has no version number) by the fact that that version of the protocol sends one, not two frames in the greeting. ZMTP/1.0 applications should reject a ZMTP/1.1 connection on the basis that the greeting has two frames, and that the first frame is not a valid identity frame, since it starts with a binary zero.
Security
ZMTP/1.1 makes no attempt at security, which an application MAY layer on top.
References
Use the zeromq-dev list to discuss this specification.
Note on use of the GPL: we use this license to cover the specification text itself, not implementations. You can license your own code under any license you wish. If you make derived versions of this specification, you must share them under the GPL. The goal of this is to prevent private extensions of our specifications.
This specification was abandoned before becoming stable (deleted).
Set the state of this specification
Specifications
11/MTL - Message Transfer Layer - Draft
10/FLP - Freelance Protocol - Draft
9/TSP - Titanic Service Protocol - Draft
6/PPP - Paranoid Pirate Protocol - Draft
4/ZPL - ZeroMQ Property Language - Draft
7/MDP - Majordomo Protocol - Stable
People who are watching this page:
