1ZMQ_PGM(7)                        0MQ Manual                        ZMQ_PGM(7)
2
3
4

NAME

6       zmq_pgm - 0MQ reliable multicast transport using PGM
7

SYNOPSIS

9       PGM (Pragmatic General Multicast) is a protocol for reliable multicast
10       transport of data over IP networks.
11

DESCRIPTION

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
18       The pgm and epgm transports can only be used with the ZMQ_PUB and
19       ZMQ_SUB socket types.
20
21       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
25           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

ADDRESSING

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
37       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
41   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
47       An interface may be specified by either of the following:
48
49       •   The interface name as defined by the operating system.
50
51       •   The primary IPv4 address assigned to the interface, in its numeric
52           representation.
53
54           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
61       A multicast address is specified by an IPv4 multicast address in its
62       numeric representation.
63

WIRE FORMAT

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
71   PGM datagram payload
72       The following ABNF grammar represents the payload of a single PGM
73       datagram as used by 0MQ:
74
75           datagram               = (offset data)
76           offset                 = 2OCTET
77           data                   = *OCTET
78
79       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
85       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
90       The following diagram illustrates the layout of a single PGM datagram
91       payload:
92
93           +------------------+----------------------+
94           | offset (16 bits) |         data         |
95           +------------------+----------------------+
96
97       The following diagram further illustrates how three example 0MQ frames
98       are laid out in consecutive PGM datagram payloads:
99
100           First datagram payload
101           +--------------+-------------+---------------------+
102           | Frame offset |   Frame 1   |   Frame 2, part 1   |
103           |    0x0000    | (Message 1) | (Message 2, part 1) |
104           +--------------+-------------+---------------------+
105
106           Second datagram payload
107           +--------------+---------------------+
108           | Frame offset |   Frame 2, part 2   |
109           | 0xFFFF       | (Message 2, part 2) |
110           +--------------+---------------------+
111
112           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

CONFIGURATION

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
123       •   The ZMQ_RATE should be set sufficiently high, e.g. 1Gbps
124
125       •   The ZMQ_RCVBUF should be increased on the subscriber, e.g. 4MB
126
127       •   The ZMQ_SNDBUF should be increased on the publisher, e.g. 4MB
128
129       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
134           # 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

EXAMPLE

141       Connecting a socket.
142
143           //  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
154

SEE ALSO

156       zmq_connect(3) zmq_setsockopt(3) zmq_tcp(7) zmq_ipc(7) zmq_inproc(7)
157       zmq_vmci(7) zmq(7)
158

AUTHORS

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.
163
164
165
1660MQ 4.3.4                         07/22/2023                        ZMQ_PGM(7)
Impressum