nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 <!-- source: doc/socat-multicast.html -->
2 <html><head>
3 <title>IP Multicasting with Socat</title>
4 <link rel="stylesheet" type="text/css" href="dest-unreach.css">
5 </head>
6  
7 <body>
8  
9 <h1>IP Multicasting with Socat</h1>
10  
11 <h2>Introduction</h2>
12 <p>
13 Multicasting (and broadcasting which is also discussed in this article)
14 provides a means to direct a single packet to more than one host. Special
15 addresses are defined for this purpose and are handled specially by network
16 adapters, networking hardware, and IP stacks.
17 </p>
18 <p>
19 IPv4 specifications provide broadcasting and multicasting; IPv6 provides
20 multicasting but replaces broadcasting by special multicast modes. UNIX domain
21 sockets do not know broadcasting or multicasting.
22 </p>
23 <p>
24 The following examples use UDP/IPv4 only. However, they can easily be
25 adapted for raw IPv4 sockets. IPv6 multicasting has not yet been successfully
26 used with socat; please contact the author if you have positive experiences or
27 ideas that go beyond <tt>IPV6_ADD_MEMBERSHIP</tt>.
28 </p>
29 <p>
30 All multicast examples presented in this document use multicast address
31 224.1.0.1; it can be replaced by any valid IPv4 multicast address (except
32 <a href="#ALLSYSTEMS">all-systems</a>).
33 </p>
34 <p>
35 We assume a local network with address 192.168.10.0 and mask 255.255.255.0; an
36 eventual "client" has 192.168.10.1, example "server" and example peer have
37 192.168.10.2 in all examples. Change these addresses and mask to your own
38 requirements.
39 </p>
40 <p>
41 All the following examples work bidirectionally except when otherwise noticed.
42 For "clients" we just use <tt>STDIO</tt>, and for "servers" we use <tt>EXEC:hostname</tt> which
43 ingores its input but shows us which host the reply comes from. Replace these
44 socat addresses with what is appropriate for your needs (e.g. shell script
45 invocations). Port 6666 can be replaced with any other port (but for ports &lt;
46 1024 root privilege might be required).
47 </p>
48 <p>
49 Different kinds of broadcast addresses exist: 255.255.255.255 is local network
50 only; for the IPv4 network 192.168.10.0/24 the "official" broadcast address
51 is 192.168.10.255; the network address 192.168.10.0 is also interpreted as
52 broadcast by some hosts. The two latter forms are routed by gateways. In the
53 following examples we only use broadcast address 192.168.10.255.
54 </p>
55  
56 <h2>Example 1: Multicast client and servers</h2>
57  
58 <p>This example builds something like a "supervisor" or "client" that
59 communicates with a set of "servers". The supervisor may send packets to the
60 multicast address, and the servers may send response packets. Note that the
61 servers would also respond to other clients' requests.</p>
62  
63 <p>Multicast server:</p>
64  
65 <span class="frame"><span class="shell">
66 socat UDP4-RECVFROM:6666,ip-add-membership=224.1.0.1:192.168.10.2,fork EXEC:hostname
67 </span></span>
68 <p>
69 This command receives multicast packets addressed to 224.1.0.1 and forks a
70 child process for each. The child processes may each send one or more reply
71 packets back to the particular sender. 192.168.10.2 means the address of the
72 interface where multicasts should be received.
73 Run this command on a number of hosts, and they will all respond in
74 parallel.</p>
75  
76 <p>Multicast client:</p>
77  
78 <span class="frame"><span class="shell">
79 socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,range=192.168.10.0/24
80 </span></span>
81 <p>
82 This process transfers data from stdin to the multicast address, and transfers
83 packets received from the local network to stdout. It does not matter in which
84 direction the first data is passed.
85 A packet from the network is accepted by the IP stack for our socket if:
86 <ul>
87 <li>it is an incoming UDP/IPv4 packet</li>
88 <li>its target port matches the local port assigned to the socket (random)</li>
89 <li>its target address matches one of the hosts local addresses or the any-host
90 multicast address</li>
91 </ul>
92 Of these packets, socat handles only those matching the following criteria:
93 <ul>
94 <li>the source address is within the given range</li>
95 <li>the source port is 6666</li>
96 </ul>
97 </p>
98  
99  
100 <h2>Example 2: Broadcast client and servers</h2>
101  
102 <p>Broadcast server:</p>
103  
104 <span class="frame"><span class="shell">
105 socat UDP4-RECVFROM:6666,broadcast,fork EXEC:hostname
106 </span></span>
107 <p>
108 This command receives packets addressed to a local broadcast address and forks
109 a child process for each. The child processes may each send one or more reply
110 packets back to the particular sender.
111 Run this command on a number of hosts, and they will all respond in
112 parallel.</p>
113  
114 <p>Broadcast client:</p>
115  
116 <span class="frame"><span class="shell">
117 socat STDIO UDP4-DATAGRAM:192.168.10.255:6666,broadcast,range=192.168.10.0/24
118 </span></span>
119 <p>
120 This process transfers data from stdin to the broadcast address, and transfers
121 packets received from the local network to stdout. It does not matter in which
122 direction the first data is passed.
123 A packet from the network is accepted by the IP stack for our socket if:
124 <ul>
125 <li>it is an incoming UDP/IPv4 packet</li>
126 <li>its target port matches the local port assigned to the socket (6666)</li>
127 <li>its target address matches one of the hosts local addresses or the any-host
128 multicast address, or a local broadcast address</li>
129 </ul>
130 Of these packets, socat handles only those matching the following criteria:
131 <ul>
132 <li>the source address is within the given range</li>
133 <li>the source port is 6666</li>
134 </ul>
135 </p>
136 <p>The <tt>broadcast</tt> option is only required for sending or receiving
137 local broadcasts.</p>
138  
139 <h2>Example 3: Multicast peers</h2>
140  
141 <p>It is possible to combine multicast sender and receiver in one socat
142 address. This allows to start processes on different hosts on the local network
143 that will communicate symmetrically, so each process can send messages that are
144 received by all the other ones.</p>
145  
146 <span class="frame"><span class="shell">
147 socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,bind=:6666,range=192.168.10.0/24,ip-add-membership=224.1.0.1:192.168.10.2
148 </span></span>
149 <p>
150 This command is valid for host 192.168.10.2; adapt this address to the
151 particular interface addresses of the hosts.
152 </p>
153 <p>
154 Starting this process opens a socket on port 6666 that will receive packets
155 directed to multicast address 224.1.0.1. Only packets with matching source
156 address and source port 6666 will be handled though. When this process sends
157 data to the network the packets will be addressed to 224.1.0.1:6666 and have a
158 source address of 192.168.10.2:6666, matching the accept criteria of the peers
159 on the local network.
160 </p>
161  
162 <p>Note: this command receives the packets it just has sent; add option
163 <tt>ip-multicast-loop=0</tt> if this in undesired.</p>
164  
165 <h2>Example 4: Broadcast peers</h2>
166  
167 <p>Just as with multicast, it is possible to combine broadcast sender and
168 receiver in one socat address.</p>
169  
170 <span class="frame"><span class="shell">
171 socat STDIO UDP4-DATAGRAM:255.255.255.255:6666,bind=:6666,range=192.168.10.0/24,broadcast
172 </span></span>
173 <p>
174 Starting this process opens a socket on port 6666 that will receive packets
175 directed to a local broadcast addresses. Only packets with matching source
176 address and source port 6666 will be handled though. When this process sends
177 data to the network the packets will be addressed to 255.255.255.255:6666 and
178 have a source address of 192.168.10.2:6666, matching the accept criteria of
179 the peers on the local network.
180 </p>
181  
182 <p>Note: this command receives the packets it just has sent; there does not
183 seem to exist a simple way to prevent this.</p>
184  
185  
186 <h2>Troubleshooting</h2>
187  
188 <p>
189 If you do not get an error message during operation, but the packets do not
190 reach the target processes, use <tt>tcpdump</tt> to see if the packets have the
191 correct source and destination addresses and ports, and if they leave and enter
192 the hosts as expected.
193 </p>
194 <p>
195 The following subsections discuss some typical sources of trouble.
196 </p>
197  
198 <h3>IP filters</h3>
199 <p>
200 If you do not succeed in receiving multicast or broadcast packets, check if
201 iptables are activated on the receiving or sending host. They might be
202 configured to disallow this traffic.
203 </p>
204  
205 <h3>Do not bind()</h3>
206 <p>
207 When using multicast communications, you should not bind the sockets to a
208 specific IP address. It seems that the (Linux) IP stack compares the
209 destination address with the bind address, not taking care of the multicast
210 property of the incoming packet.
211 </p>
212  
213 <h3>Routing</h3>
214 <p>
215 When you receive an error like:</p>
216 <table border="1" bgcolor="#e08080"><tr><td><tt>... E sendto(3, 0x80c2e44, 4,
217 0, AF=2 224.1.0.1:6666, 16): Network is unreachable</tt></td></tr></table>
218 <p>you have a routing problem. The (Linux) IP stack seems to handle multicast
219 addresses just like unicast addresses when determining their route (interface
220 and gateway), i.e. the routing table needs an entry that somehow matches the
221 target address. </p>
222 <p>
223 For the same reason, multicast packets will probably leave your host on the
224 interface with the default route if it is specified.</p>
225 <p>
226 Set a multicast/broadcast route with the following command (Linux):</p>
227 <span class="frame"><span class="shell">
228 route add -net 224.0.0.0/3 gw 192.168.10.2
229 </span></span>
230  
231 <a name="ALLSYSTEMS"></a>
232 <h3>ALL-SYSTEMS multicast address</h3>
233 <p>
234 <tt>224.0.0.1</tt> is the all-systems multicast address: all
235 datagram sockets appear to be automatically member of this group on all
236 interfaces. This membership cannot be dropped on Linux (you need iptables to
237 filter packets).
238 </p>
239  
240  
241 <h2>(In)Security</h2>
242  
243 <p>When you use the above examples you should understand that all datagram
244 sockets without exception accept all packets that are directly addressed to
245 them;
246 the multi- and broadcast receiving features are just extensions to this
247 functionality. socat currently has no means to handle incoming packets
248 differently whether they are addressed to unicast, multicast, or broadcast
249 addresses. However, for EXEC'd scripts socat can provide this info in
250 environment variables.
251 </p>
252  
253 <p>Authentication or encryption are not available.</p>
254  
255 <p>It is very easy to fake the source address of UDP (or raw IP) packets. You
256 should understand whether your network is protected from address spoofing
257 attacks.</p>
258  
259 <p>Broadcast and multicast traffic can trivially be received by <em>any</em>
260 host on the local network.</p>
261  
262  
263 <h2>History</h2>
264  
265 Starting with version 1.5.0, socat provides a set of address types that
266 allow various operations on datagram oriented sockets:
267 <dl>
268 <dt>SENDTO</dt><dd>send packets to a remote socket and receive packet from this
269 remote socket only</dd>
270 <dt>RECV</dt><dd>receive all packets that arrive on the local socket, but do
271 not reply</dd>
272 <dt>RECVFROM</dt><dd>receive all packets that arrive on the local socket, and
273 reply using child processes</dd>
274 </dl>
275  
276 <p>
277 These modes already enable several different client/server oriented operations.
278 Moreover, the SENDTO addresses can send to multicast and broadcast addresses
279 (the latter requires the <tt>broadcast</tt> option though). RECV and RECVFROM
280 also would accept packets addressed to a local broadcast address (with option
281 <tt>broadcast</tt>) or the all-systems multicast address.
282 </p>
283  
284 <p>
285 These address types had, however, two major caveats:
286 <ul>
287 <li>Missing control of multicast group membership in the RECV and RECVFROM
288 addresses</li>
289 <li>The SENDTO address would never accept a reply to a broadcast or multicast
290 addressed packet because the source address of incoming replies would not match
291 the target address of the sent packet.
292 </ul>
293 </p>
294  
295 <h3>New Features in socat 1.6.0</h3>
296  
297 <p>
298 socat version 1.6.0 addresses these problems and provides a new more generic
299 datagram address type (*-DATAGRAM) and the new address option IP-ADD-MEMBERSHIP.
300 </p>
301  
302 <p>
303 Please note that the new features could not be successfully tested on IPv6;
304 these sections thus apply to IPv4 only.
305 </p>
306  
307 <h3>New Features in socat 1.7.0</h3>
308  
309 <p>
310 socat version 1.7.0 helps to find more information about incoming packets in
311 environment variables that can be used in scripts or programs invoked by
312 socat. The option <tt>ip-pktinfo</tt> (on non-BSD systems)
313 or <tt>ip-recvdstaddr</tt> (on BSD systems) is required to get basic
314 information about incoming packets.
315 </p>
316  
317 <p>
318 Example: Start a receiver of the following form (tried on Linux):
319 </p>
320  
321 <span class="frame"><span class="shell">
322 socat -u UDP-RECVFROM:8888,reuseaddr,ip-add-membership=224.1.0.1:192.168.10.2,ip-pktinfo,fork SYSTEM:export
323 </span></span>
324  
325 <p>
326 Then send a multicast packet from the client:
327 </p>
328  
329 <span class="frame"><span class="shell">
330 echo |socat -u STDIO UDP-DATAGRAM:224.1.0.1:8888
331 </span></span>
332  
333 <p>
334 On the server the following text should appear (only interesting lines shown):
335 </p>
336  
337 <pre>
338 export SOCAT_IP_DSTADDR="224.1.0.1"
339 export SOCAT_IP_IF="eth0"
340 export SOCAT_IP_LOCADDR="192.168.10.2"
341 export SOCAT_PEERADDR="192.168.10.1"
342 export SOCAT_PEERPORT="41159"
343 </pre>
344  
345 <p>
346 <tt>SOCAT_IP_IF</tt> shows the interface where the packet entered the server;
347 <tt>SOCAT_IP_LOCADDR</tt> shows the IP address of this interface;
348 <tt>SOCAT_IP_DSTADDR</tt> shows the target address of the packet;
349 <tt>SOCAT_PEERADDR</tt> and <tt>SOCAT_PEERPORT</tt> are the client socket
350 values.
351 </p>
352  
353 <h2>More info about socat datagrams</h2>
354  
355 <h3>Links regarding this tutorial</h3>
356 <a href="socat.html#ADDRESS_UDP4_DATAGRAM">address UDP4-DATAGRAM</a><br>
357 <a href="socat.html#ADDRESS_UDP4_RECVFROM">address UDP4-RECVFROM</a><br>
358 <a href="socat.html#OPTION_RANGE">option range</a><br>
359 <a href="socat.html#OPTION_SO_BROADCAST">option broadcast</a><br>
360 <a href="socat.html#OPTION_IP_ADD_MEMBERSHIP">option ip-add-membership</a><br>
361 <a href="socat.html#OPTION_FORK">option fork</a><br>
362 <a href="socat.html#OPTION_BIND">option bind</a><br>
363  
364 <h3>Other datagram addresses</h3>
365 <a href="socat.html#ADDRESS_UDP4_RECV">address UDP4-RECV</a>: pure datagram receiver<br>
366 <a href="socat.html#ADDRESS_UDP4_SENDTO">address UDP4-SENDTO</a>: communicate
367 with one peer address<br>
368 <a href="socat.html#ADDRESS_UDP4_LISTEN">address UDP4-LISTEN</a>: pseudo stream server<br>
369 <a href="socat.html#ADDRESS_UDP4_CONNECT">address UDP4-CONNECT</a>: pseudo stream client<br>
370  
371 <h3>Related socat option groups</h3>
372 <a href="socat.html#GROUP_IP">IP options</a><br>
373 <a href="socat.html#GROUP_SOCKET">socket options</a><br>
374 <a href="socat.html#GROUP_FD">file descriptor options</a><br>
375 <a href="socat.html#GROUP_RANGE">range options</a><br>
376 <a href="socat.html#GROUP_CHILD">child process options</a><br>
377  
378  
379 <h2>References</h2>
380 <a href="http://www.dest-unreach.org/socat">socat home page</a><br>
381 <a href="socat.html">socat man page</a><br>
382 <a href="http://en.wikipedia.org/wiki/Multicast">multicasting on Wikipedia</a><br>
383 <a href="http://en.wikipedia.org/wiki/Broadcast_address">broadcasting on Wikipedia</a><br>
384  
385 <p>
386 <small>This document was last modified in May 2009.</small><br>
387 <small>Copyright: Gerhard Rieger 2007-2009</small><br>
388 <small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
389 </p>
390  
391 </body>
392 </html>