doc/socat-multicast.html

   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>