1ZMQ_PGM(7) 0MQ Manual ZMQ_PGM(7)
2
6 zmq_pgm - 0MQ reliable multicast transport using PGM
7
9 PGM (Pragmatic General Multicast) is a protocol for reliable multicast
10 transport of data over IP networks.
11
13 0MQ implements two variants of PGM, the standard protocol where PGM
14 datagrams are layered directly on top of IP datagrams as defined by RFC
15 3208 (the pgm transport) and "Encapsulated PGM" or EPGM where PGM
16 datagrams are encapsulated inside UDP datagrams (the epgm transport).
17 The pgm and epgm transports can only be used with the ZMQ_PUB and
19 ZMQ_SUB socket types.
20 Further, PGM sockets are rate limited by default. For details, refer to
22 the ZMQ_RATE, and ZMQ_RECOVERY_IVL options documented in
23 zmq_setsockopt(3).
24 Caution
26 The pgm transport implementation requires access to raw IP sockets.
27 Additional privileges may be required on some operating systems for
28 this operation. Applications not requiring direct interoperability
29 with other PGM implementations are encouraged to use the epgm
30 transport instead which does not require any special privileges.
31
33 A 0MQ endpoint is a string consisting of a transport:// followed by an
34 address. The transport specifies the underlying protocol to use. The
35 address specifies the transport-specific address to connect to.
36 For the PGM transport, the transport is pgm, and for the EPGM protocol
38 the transport is epgm. The meaning of the address part is defined
39 below.
40 Connecting a socket
42 When connecting a socket to a peer address using zmq_connect() with the
43 pgm or epgm transport, the endpoint shall be interpreted as an
44 interface followed by a semicolon, followed by a multicast address,
45 followed by a colon and a port number.
46 An interface may be specified by either of the following:
48 • The interface name as defined by the operating system.
50 • The primary IPv4 address assigned to the interface, in its numeric
52 representation.
53 Note
55 Interface names are not standardised in any way and should be
56 assumed to be arbitrary and platform dependent. On Win32 platforms
57 no short interface names exist, thus only the primary IPv4 address
58 may be used to specify an interface. The interface part can be
59 omitted, in that case the default one will be selected.
60 A multicast address is specified by an IPv4 multicast address in its
62 numeric representation.
63
65 Consecutive PGM datagrams are interpreted by 0MQ as a single continuous
66 stream of data where 0MQ messages are not necessarily aligned with PGM
67 datagram boundaries and a single 0MQ message may span several PGM
68 datagrams. This stream of data consists of 0MQ messages encapsulated in
69 frames as described in zmq_tcp(7).
70 PGM datagram payload
72 The following ABNF grammar represents the payload of a single PGM
73 datagram as used by 0MQ:
74 datagram = (offset data)
76 offset = 2OCTET
77 data = *OCTET
78 In order for late joining consumers to be able to identify message
80 boundaries, each PGM datagram payload starts with a 16-bit unsigned
81 integer in network byte order specifying either the offset of the first
82 message frame in the datagram or containing the value 0xFFFF if the
83 datagram contains solely an intermediate part of a larger message.
84 Note that offset specifies where the first message begins rather than
86 the first message part. Thus, if there are trailing message parts at
87 the beginning of the packet the offset ignores them and points to first
88 initial message part in the packet.
89 The following diagram illustrates the layout of a single PGM datagram
91 payload:
92 +------------------+----------------------+
94 | offset (16 bits) | data |
95 +------------------+----------------------+
96 The following diagram further illustrates how three example 0MQ frames
98 are laid out in consecutive PGM datagram payloads:
99 First datagram payload
101 +--------------+-------------+---------------------+
102 | Frame offset | Frame 1 | Frame 2, part 1 |
103 | 0x0000 | (Message 1) | (Message 2, part 1) |
104 +--------------+-------------+---------------------+
105 Second datagram payload
107 +--------------+---------------------+
108 | Frame offset | Frame 2, part 2 |
109 | 0xFFFF | (Message 2, part 2) |
110 +--------------+---------------------+
111 Third datagram payload
113 +--------------+----------------------------+-------------+
114 | Frame offset | Frame 2, final 8 bytes | Frame 3 |
115 | 0x0008 | (Message 2, final 8 bytes) | (Message 3) |
116 +--------------+----------------------------+-------------+
117
119 The PGM is protocol is capable of multicasting data at high rates
120 (500Mbps+) with large messages (1MB+), however it requires setting the
121 relevent ZMQ socket options that are documented in zmq_setsockopt(3):
122 • The ZMQ_RATE should be set sufficiently high, e.g. 1Gbps
124 • The ZMQ_RCVBUF should be increased on the subscriber, e.g. 4MB
126 • The ZMQ_SNDBUF should be increased on the publisher, e.g. 4MB
128 It’s important to note that the ZMQ_RCVBUF and ZMQ_SNDBUF options are
130 limited by the underlying host OS tx/rx buffer size limit. On linux,
131 these can be increased for the current session with the following
132 commands:
133 # set tx/rx buffers to 4MB (default can also be read as the initial buffer size)
135 sudo sysctl -w net.core.rmem_max=4194304
136 sudo sysctl -w net.core.wmem_max=4194304
137 sudo sysctl -w net.core.rmem_default=4194304
138 sudo sysctl -w net.core.wmem_default=4194304
139
141 Connecting a socket.
142 // Connecting to the multicast address 239.192.1.1, port 5555,
144 // using the first Ethernet network interface on Linux
145 // and the Encapsulated PGM protocol
146 rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
147 assert (rc == 0);
148 // Connecting to the multicast address 239.192.1.1, port 5555,
149 // using the network interface with the address 192.168.1.1
150 // and the standard PGM protocol
151 rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
152 assert (rc == 0);
153
156 zmq_connect(3) zmq_setsockopt(3) zmq_tcp(7) zmq_ipc(7) zmq_inproc(7)
157 zmq_vmci(7) zmq(7)
158
160 This page was written by the 0MQ community. To make a change please
161 read the 0MQ Contribution Policy at
162 http://www.zeromq.org/docs:contributing.
1630MQ 4.3.4 07/22/2023 ZMQ_PGM(7)