doc/socat-genericsocket.html

   1 <html><head>
   2 <title>Generic sockets with Socat</title>
   3 <link rel="stylesheet" type="text/css" href="dest-unreach.css">
   4 </head>
   5
   6 <body>
   7
   8 <h1>Generic sockets with Socat</h1>
   9
  10 <h2>Introduction</h2>
  11 <p>Beginning with version 1.7.0 socat provides means to freely control
  12   important aspects of socket handling. This allows to experiment with socket
  13   types and protocols that are not explicitely implemented in socat.
  14 </p>
  15
  16 <p>The related socat features fall into three major categories:<p>
  17
  18 <ul>
  19   <li>address options for changing socket parameters while using common
  20     socket types:
  21     <tt>pf (protocol-family), so-type (socktype), so-prototype (protocol)</tt>
  22   </li>
  23   <li>address options for setting arbitrary socket options:
  24     <tt>setsockopt-int, setsockopt-string, setsockopt-bin</tt></li>
  25   <li>address types for passing almost arbitrary parameters and address data to
  26     the standard system calls:
  27     <tt>socket-connect, socket-listen, socket-sendto, socket-recv,
  28       socket-recvfrom, socket-datagram</tt></li>
  29 </ul>
  30
  31 <p>In practice this gives you two possibilities:</p>
  32
  33 <p>If you want to cope with sockets staying within the usual domains ( =
  34   protocol families = address families) which are IPv4, IPv6, UNIX/local, and
  35   raw interface for socat 1.7.0, it is sufficient to learn about a couple of
  36   <a href="#GENERIC_OPTIONS">address options</a> that allow to change default
  37   parameters, and to apply generic socket options.</p>
  38
  39 <p>For other address families socat provides <a
  40 href="#GENERIC_ADDRESSES">generic socket addresses</a>.
  41 </p>
  42
  43
  44 <a name="GENERIC_OPTIONS"></a>
  45 <h2>Generic socket options</h2>
  46
  47 <h3>Example 1: DCCP communication</h3>
  48
  49 <p>A relatively new communication protocol has been introduced in the Internet
  50   community for which no socat address type has been implemented up to version
  51   1.7.0
  52   (see <a href="http://www.ietf.org/html.charters/dccp-charter.html">IETF's
  53   Datagram Congestion Control Protocol</a>
  54   and <a href="http://www.linuxfoundation.org/en/Net:DCCP#python_support">Linux
  55   foundation Net:DCCP</a> for more info). Taken that the
  56   operating system implements DCCP, it is possible to use this protocol
  57   with socat while just employing standard socket addresses and some options.
  58 </p>
  59
  60 <p>A simple server that accepts a DCCP connection, passes the arriving data to a
  61   subprocess for converting upper case to lower case characters, and then
  62   returns it to the client:
  63 </p>
  64
  65 <span class="frame"><span class="shell">
  66 socat TCP4-LISTEN:4096,reuseaddr,type=6,prototype=33 exec:'tr A-Z a-z',pty,raw,echo=0
  67 </span></span>
  68
  69 <p>A simple client that sends some upper case characters to the server via DCCP
  70   and prints what the server returns:
  71 </p>
  72
  73 <span class="frame"><span class="shell">
  74 echo ABCD |socat - TCP4-CONNECT:localhost:4096,type=6,prototype=33
  75 </span></span>
  76
  77 <p>We choose the TCP4 addresses as base because it best matches the DCCP
  78   requirements:
  79   <ol>
  80     <li>DCCP is (here) based on IPv4</li>
  81     <li>DCCP is stream oriented and uses <tt>connect()</tt> and <tt>listen();
  82         accept()</tt> calls</li>
  83     <li>DCCP protocol uses ports</li>
  84   </ol>
  85 </p>
  86
  87 <p>Option <tt><a href="socat.html#OPTION_SO_TYPE">type</a>=6</tt> changes TCP's
  88   <tt>SOCK_STREAM</tt> parameter to <tt>SOCK_DCCP</tt>, and <tt>
  89     <a href="socat.html#OPTION_SO_PROTOTYPE">prototype</a>=33</tt> replaces the
  90   default <tt>IPPROTO_TCP</tt> with <tt>IPPROTO_DCCP</tt>.
  91 </p>
  92
  93 <p>DCCP has an important parameter, the service code. It provides another
  94   multiplexing layer beyond the protocol ports. The Linux implementation of DCCP
  95   allows to set this parameter with code like <tt>setsocktopt(fd, SOL_DCCP,
  96   DCCP_SOCKOPT_SERVICE, {1}, sizeof(int))</tt>. The equivalent generic socat
  97   option is: <tt><a href="socat.html#OPTION_SETSOCKOPT_INT">setsockopt-int</a>=269:2:1</tt> for service code 1.
  98   If the service codes on server and client do not match the <tt>connect()</tt>
  99   operation fails with error:<p>
 100
 101 <table border="1" bgcolor="e08080"><tr><td><tt>... E connect(3, AF=2 127.0.0.1:4096, 16): Invalid request code</tt></td></tr></table>
 102
 103 <p>Please note that this examples works with IPv6 as well, you just need to
 104   replace the TCP4 words with TCP6, and the IPv4 socket address with an
 105   appropriate IPv6 socket address, e.g. <tt>[::1]</tt>!
 106 </p>
 107
 108 <a name="GENERIC_ADDRESSES"></a>
 109 <h2>Generic socket addresses</h2>
 110
 111 <p>socat's generic socket addresses are a more comprehensive mechanism that
 112   allows to deal with protocol families whose socket addresses are not supported
 113   by socat - no semantical parsing, no structured assignment to the struct
 114   components are available. Instead, the socket address records for binding and
 115   connecting/sending are specified in unstructured hexadecimal form. The
 116   following example demonstrates this by performing simple data transfer over
 117   raw AppleTalk protocol.
 118 </p>
 119
 120 <p>Note: I do not have any knowledge about AppleTalk. I just managed to
 121   configure my Linux host to tolerate the creation of a receiving and a sending
 122   socket. Don't blame me nor ask me for support if it does not work for you.
 123 </p>
 124
 125 <a name="EXAMPLE_APPLETALK"></a>
 126 <h3>Enabling AppleTalk protocol</h3>
 127
 128 <p>Install the <tt>netatalk</tt> package. Check that <tt>/etc/netatalk/atalkd.conf</tt>
 129   has an entry like <tt>eth0 -phase 2 -net 0-65534 -addr 65280.243</tt>. The
 130   last part is an arbitrary (?) host address, some of the following values must
 131   fit it. Make sure the <tt>atalkd</tt> daemon is running. Run the AppleTalk
 132   ping command:
 133 </p>
 134
 135 <span class="frame"><span class="shell">
 136 aecho 65280.243
 137 </span></span>
 138
 139 <p>If you get an error like:
 140 </p>
 141
 142 <table border="1" bgcolor="#e08080"><tr><td><tt>Device or resource busy</tt></td></tr></table>
 143
 144 <p>then try to restart <tt>atalkd</tt>:</p>
 145
 146 <span class="frame"><span class="shell">
 147 /etc/init.d/atalkd restart
 148 </span></span>
 149
 150 <p>When <tt>aecho</tt> works like <tt>ping</tt> you are ready for the next step.
 151 </p>
 152
 153 <h3>Example 2: AppleTalk datagram communication</h3>
 154
 155 <p>We start a socat process with a receiver and echo service:
 156 </p>
 157
 158 <span class="frame"><span class="shell">
 159 socat SOCKET-RECVFROM:5:2:0:x40x00x0000x00x00x0000000000000000 PIPE
 160 </span></span>
 161
 162 <p>Then, in another shell on the same host, we start a client socket process
 163   that sends data to the server and gets the answer:
 164 </p>
 165
 166 <span class="frame"><span class="shell">
 167 echo ABCD |socat - SOCKET-DATAGRAM:5:2:0:x40x00xff00xf3x00x0000000000000000
 168 </span></span>
 169
 170 <p>The client process should print the data.
 171 </p>
 172
 173 <p>How did this work? The generic socat address has just used the system call
 174   parameters that were provided on command line, without knowing anything about
 175   AppleTalk sockets and protocol. The values 5, 2, and 0 are directly used for
 176   the <tt>socket()</tt> call: they specify the domain (<tt>PF_APPLETALK=5</tt>),
 177   socket type (<tt>SOCK_DGRAM=2</tt>), and no protocol (0) - values for Linux.
 178   The long hex strings define the socket addresses. They can only be constructed
 179   with knowledge of the underlying structure. In
 180   <tt>/usr/include/linux/atalk.h</tt> we find the following declarations:
 181 </p>
 182
 183 <pre>
 184 struct atalk_addr {
 185         __be16  s_net;
 186         __u8    s_node;
 187 };
 188
 189 struct sockaddr_at {
 190         sa_family_t       sat_family;
 191         __u8              sat_port;
 192         struct atalk_addr sat_addr;
 193         char              sat_zero[8];
 194 </pre>
 195
 196 <p>After rolling out <tt>atalk_addr</tt> and considering implicit padding by the
 197  C programming language we get the following byte map:
 198 </p>
 199
 200 <table border="1">
 201 <tr><th>component</th><th>offset</th><th>length</th><th>value</th><th>meaning</th></tr>
 202 <tr><td>sat_family</td><td>0</td><td>2</td><td>x0005</td><td>address family</td></tr>
 203 <tr><td>sat_port</td><td>2</td><td>1</td><td>x40</td><td>port</td></tr>
 204 <tr><td>-</td><td>3</td><td>1</td><td>x00</td><td>padding</td></tr>
 205 <tr><td>sat_addr.s_net</td><td>4</td><td>2</td><td>xff00</td><td>network address</td></tr>
 206 <tr><td>sat_addr.s_node</td><td>6</td><td>1</td><td>xf3</td><td>node address</td></tr>
 207 <tr><td>-</td><td>7</td><td>1</td><td>x00</td><td>padding</td></tr>
 208 <tr><td>sat_zero</td><td>8</td><td>8</td><td>x0000000000000000</td><td>padding</td></tr>
 209 </table>
 210
 211 <p>Note that hexadecimal ff00 is the same as decimal 65280, and hexadecimal xf3
 212   is the same as decimal 243 - these are the numbers specified in
 213   <tt>atalkd.conf</tt>.
 214 </p>
 215
 216 <p>The address family component must be omitted from the socket address because
 217   it is added by socat implicitely. The resulting hexadecimal representation of
 218   the target socket address is therefore:
 219 </p>
 220 <tt>x40x00xff00xf3x00x0000000000000000</tt>
 221
 222 <p>The receiver just has to specify the port, so its bind address data is:
 223 </p>
 224 <tt>x40x00x0000x00x00x0000000000000000</tt>
 225
 226 <h2>Parameters for well known socket types</h2>
 227
 228 <p>Finding the correct parameters and socket addresses is not always trivial.
 229   Therefore this section provides tables with the parameters of common socket
 230   types. Some of these types are directly implemented by socat (and other
 231   programs). Establishing interoperability between a directly implemented
 232   socket and a generic socket might be your first step before entering unknown
 233   ground.</p>
 234
 235 <h3>Socket parameters</h3>
 236
 237 <h4>Table: parameter names for "well known" sockets:</h4>
 238
 239 <table border=1>
 240 <tr><th>name</th><th>domain</th><th>socktype</th><th>protocol</th><th> </th><th>level</th><th>remark</th></tr>
 241 <tr><td>UDP4</td><td>PF_INET</td><td>SOCK_DGRAM</td><td>IPPROTO_UDP</td><td> </td><td>SOL_UDP</td><td></td></tr>
 242 <tr><td>UDP6</td><td>PF_INET6</td><td>SOCK_DGRAM</td><td>IPPROTO_UDP</td><td> </td><td>SOL_UDP</td><td></td></tr>
 243 <tr><td>raw IPv4</td><td>PF_INET</td><td>SOCK_RAW</td><td>IPPROTO_RAW</td><td> </td><td>SOL_IP</td><td></td></tr>
 244 <tr><td>raw IPv6</td><td>PF_INET6</td><td>SOCK_RAW</td><td>IPPROTO_RAW</td><td> </td><td>SOL_IPV6</td><td></td></tr>
 245 <tr><td>UNIX</td><td>PF_LOCAL</td><td>SOCK_DGRAM</td><td>0</td><td> </td><td>SOL_SOCKET</td><td> </td></tr>
 246 <tr><td>PACKET</td><td>PF_PACKET</td><td>SOCK_RAW</td><td>768</td><td></td><td>SOL_PACKET</td><td>tcpdump (include layer 2 header)</td></tr>
 247 <tr><td>PACKET</td><td>PF_PACKET</td><td>SOCK_DGRAM</td><td>768</td><td></td><td>SOL_PACKET</td><td>no level 2 header</td></tr>
 248 <tr><td>SCTP4</td><td>PF_INET</td><td>SOCK_SEQPACKET</td><td>IPPROTO_SCTP</td><td> </td><td>SOL_SCTP</td><td> </td></tr>
 249 </table>
 250
 251 <h4>Table: parameter values:</h4>
 252
 253 <table border=1>
 254 <tr><th>name</th><th>Linux</th><th>FreeBSD</th><th>NetBSD</th><th>OpenBSD</th><th>Solaris</th><th>AIX</th><th>Cygwin</th><th>Mac OS X</th><th>HP-UX</th></tr>
 255 <tr><td>PF_LOCAL</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
 256 <tr><td>PF_INET</td><td>2</td><td>2</td><td>2</td><td>2</td><td>2</td><td>2</td><td>2</td><td>2</td><td>2</td></tr>
 257 <tr><td>PF_APPLETALK</td><td>5</td><td>16</td><td>16</td><td>16</td><td>16</td><td>16</td><td>16</td><td>16</td><td>16</td></tr>
 258 <tr><td>PF_INET6</td><td>10</td><td>28</td><td>24</td><td>24</td><td>26</td><td>24</td><td>-</td><td>30</td><td>22</td></tr>
 259 <tr><td>PF_PACKET</td><td>17</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 260 <tr><td>SOCK_STREAM</td><td>1</td><td>1</td><td>1</td><td>1</td><td>2</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
 261 <tr><td>SOCK_DGRAM</td><td>2</td><td>2</td><td>2</td><td>2</td><td>1</td><td>2</td><td>2</td><td>2</td><td>2</td></tr>
 262 <tr><td>SOCK_RAW</td><td>3</td><td>3</td><td>3</td><td>3</td><td>4</td><td>3</td><td>3</td><td>3</td><td>3</td></tr>
 263 <tr><td>SOCK_SEQPACKET</td><td>5</td><td>5</td><td>5</td><td>5</td><td>6</td><td>5</td><td>5</td><td>5</td><td>5</td></tr>
 264 <tr><td>SOCK_DCCP</td><td>(6)</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 265 <tr><td>SOCK_PACKET</td><td>10</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 266 <tr><td>IPPROTO_IP</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td></tr>
 267 <tr><td>IPPROTO_TCP</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td></tr>
 268 <tr><td>IPPROTO_UDP</td><td>17</td><td>17</td><td>17</td><td>17</td><td>17</td><td>17</td><td>17</td><td>17</td><td>17</td></tr>
 269 <tr><td>IPPROTO_DCCP</td><td>33</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 270 <tr><td>IPPROTO_SCTP</td><td>132</td><td>132</td><td>-</td><td>-</td><td>132</td><td>132</td><td>-</td><td>-</td><td>-</td></tr>
 271 <tr><td>IPPROTO_RAW</td><td>255</td><td>255</td><td>255</td><td>255</td><td>255</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 272 <tr><td>SOL_SOCKET</td><td>1</td><td>65535</td><td>65535</td><td>65535</td><td>65535</td><td>65535</td><td>65535</td><td>65535</td><td>65535</td></tr>
 273 <tr><td>SOL_IP</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td></tr>
 274 <tr><td>SOL_TCP</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td><td>6</td></tr>
 275 <tr><td>SOL_UDP</td><td>17</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>17</td><td>-</td><td>-</td></tr>
 276 <tr><td>SOL_IPV6</td><td>41</td><td>41</td><td>41</td><td>41</td><td>41</td><td>41</td><td>-</td><td>41</td><td>41</td></tr>
 277 <tr><td>SOL_PACKET</td><td>263</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 278 <tr><td>SOL_DCCP</td><td>269</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr>
 279 </table>
 280
 281
 282 <h3>Socket address specifications</h3>
 283
 284 <p>These hexadecimal data define socket addresses for local and remote sockets,
 285 and for bind and range options. The basis is the <tt>struct sockaddr_*</tt> for
 286 the respective address family that should be declared in the C include files.
 287 Please keep in mind that their first two bytes (<tt>sa_family</tt> and - on BSD
 288 - <tt>sa_len</tt>) are implicitely prepended by socat.</p>
 289
 290 <h4>Linux on 32bit Intel:</h4>
 291
 292 <table border=1>
 293 <tr><th>name</th><th>socket address type (without leading address family)</th><th>binary specification</th></tr>
 294 <tr><td>IPv4</td><td>2 bytes port, 4 bytes IPv4 addr, 8 bytes 0</td><td>x0016
 295 x7f000001 x0000000000000000</td></tr>
 296 <tr><td>IPv6</td><td>2 bytes port, 4 bytes flowinfo, 16 bytes IPv6 addr, 4 bytes scope-id</td><td>x0016 x00000000 x0102030405060708090a0b0c0d0e0f x00000000</td></tr>
 297 <tr><td>UNIX</td><td>variable length path name, 0 terminated</td><td>x2f746d702f736f636b00</td></tr>
 298 <tr><td>PACKET</td><td>2 bytes protocol (0x0003), interface index as int in host byte order, 8 bytes 0</td><td>x0003 x02000000 x0000000000000000</td></tr>
 299 </table>
 300
 301 <p>For AppleTalk see above <a href="#EXAMPLE_APPLETALK">example</a>.</p>
 302
 303 <h4>Solaris on 32bit Intel:</h4>
 304
 305 <table border=1>
 306 <tr><th>name</th><th>socket address type (without leading address family)</th><th>binary specification</th></tr>
 307 <tr><td>IPv6</td><td>2 bytes port, 4 bytes flowinfo, 16 bytes IPv6 addr, 4
 308     bytes scope-id, 4 bytes src-id</td><td>x0016 x00000000 x0102030405060708090a0b0c0d0e0f x00000000 x00000000</td></tr>
 309 </table>
 310
 311 <h3>Forever - play on...</h3>
 312
 313 <p>Eager to experiment with exotic socket types? Run nmap's protocol scan and
 314 see what is available on your system:
 315 </p>
 316
 317 <span class="frame"><span class="shell">
 318 nmap -sO localhost
 319 </span></span>
 320
 321 <p>
 322 <small>Copyright: Gerhard Rieger 2008</small><br>
 323 <small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
 324 </p>
 325
 326 </body>
 327 </html>