components/network/tuntap/files/README-tuntap.html

   1 <html>
   2 <head>
   3 <title>
   4 TAP driver for Solaris
   5 </title>
   6 </head>
   7 <body>
   8
   9 <table border="0" style="width:100%">
  10 <tr><td>
  11 <h1><b>TAP driver for Solaris used for OpenVPN<br> and any other virtual network solution. </b></h1>
  12 </td>
  13 <td align="right">
  14
  15 </td></tr></table>
  16 <p>
  17 This is a TAP driver for Solaris that can be used for
  18 <a href="http://openvpn.net/">OpenVPN</a>,
  19 <a href="http://www.infradead.org/openconnect.html">OpenConnect</a>,
  20 <a href="http://www.unix-ag.uni-kl.de/~massar/vpnc/">vpnc</a><br>
  21 The code is based on <a href="http://vtun.sourceforge.net/tun/">
  22 Universal TUN/TAP driver</a>.
  23 I made changes somewhat and added some code to it for supporting Ethernet
  24 tunneling feature, since Universal TUN/TAP driver for Solaris only supports
  25 IP tunneling known as TUN. <br><br>
  26 <S>Since there has not been TAP driver for Solaris, OpenVPN does not have code
  27 for handling a TAP device for Solaris. So I also modified OpenVPN code somewhat,
  28 and made it work with this TAP driver.<br></S>
  29 OpenVPN patch has been merged into OpenVPN 2.2.0.(2011.04.28).<P>
  30
  31 Also, I wrote bridge moduel for Solaris, so that you can configure Solaris as
  32 bridge server.
  33
  34 <blockquote>
  35 <ul>
  36 <li><a href="#tap">TAP Driver</a><br>
  37 <li><a href="#openvpn">Patch for OpenVPN</a><br>
  38 <li><a href="#bridge">Bridge Module</a><br>
  39 <li><a href="#tunctl">tunctl command for Solaris</a><br>
  40 <br>
  41 <li><a href="#test">Tested Solaris Version</a><br>
  42 <li><a href="#change">Change Log</a><br>
  43 </ul>
  44 </blockquote>
  45
  46 <hr>
  47 <a name="tap"><h3>TAP driver </h3></a>
  48 <ul>
  49 <li><a href="https://github.com/kaizawa/tuntap/tarball/master">tuntap.tar.gz</a> (Last Update: 17th Jul 2012)
  50 <li><a href="http://github.com/kaizawa/tuntap">Source</a><p>
  51
  52    After extracting tuntap.tar.gz file, run './configure', 'make', and 'make install' as usual.<br>
  53    Both 'tun' and 'tap' driver will be built and installed on your system. You can access
  54    these devices through /dev/tun and /dev/tap.
  55 <br><br>
  56 </ul>
  57 <p>
  58 <hr>
  59 <a name="openvpn"><h3>Patch for OpenVPN</h3></a>
  60 Patch for OpenVPN has been merged into OpenVPN 2.2.0. (2011.04.28).<br>
  61 So if you are going to use OpenVPN 2.2.0 or later, you don't need to apply following patch.<p>
  62 <ul>
  63 <li>tun.c
  64 <br><br>
  65 <table border="1">
  66 <tr>
  67         <td>OpenVPN Version</td><td>Modified file</td><td>patch(diff -u ouputs)</td><td>Last Update</td>
  68 </tr>
  69 <tr>
  70         <td>2.0.7, 2.0.9</td><td><a href="http://github.com/downloads/kaizawa/openvpn-patch/tun.c.2.0.9">tun.c.2.0.9</a></td>
  71          <td><a href="http://github.com/downloads/kaizawa/openvpn-patch/patch.openvpn-2.0.9.tun.c">patch.openvpn-2.0.9.tun.c</td>
  72         <td>20th May 2009</td>
  73 </tr>
  74
  75 <tr>
  76         <td>2.1.1</td><td><a href="http://github.com/downloads/kaizawa/openvpn-patch/tun.c.2.1.1">tun.c.2.1.1</a></td>
  77         <td><a href="http://github.com/downloads/kaizawa/openvpn-patch/patch.openvpn-2.1.1.tun.c">patch.openvpn-2.1.1.tun.c</a></td>
  78         <td>29th Apr 2010</td>
  79 </tr>
  80 <tr>
  81         <td>2.1.3</td><td><a href="http://github.com/downloads/kaizawa/openvpn-patch/tun.c.2.1.3">tun.c.2.1.3</a></td>
  82         <td><a href="http://github.com/downloads/kaizawa/openvpn-patch/patch.openvpn-2.1.3.tun.c">patch.openvpn-2.1.3.tun.c</a></td>
  83         <td>31th Aug 2010</td>
  84 </tr>
  85 <tr>
  86         <td>2.2.0 -</td><td>n/a</td>
  87         <td>n/a</a></td>
  88         <td></td>
  89 </tr>
  90 </table>
  91 <br>
  92 <li>How to apply
  93   <br><br>
  94   <ul>
  95   <li><b>By replacing file</b>
  96   <br>
  97 Put tun.c on the directory where you extracted source code of OpenVPN, and swap existing tun.c
  98 file for it.<br>
  99 Please note that you should rename tun.c.&lt;version&gt; to tun.c file.
 100   <br>
 101   <li><b>By patch(1) command</b>
 102   <br>
 103 If you want to apply patch(1), put patch.openvpn-xxx.tun.c on the directory where you extracted
 104 source code of OpenVPN, and run patch(1) command like as below.<br>
 105     <pre>
 106   $ patch -p1 < patch.openvpn-xxxx.tun.c
 107     </pre>
 108   </ul>
 109
 110 NOTE: Please download appropriate file which correspond to the version of OpenVPN.<br>
 111 Otherwise, you'll get an error while building a openvpn binary.
 112 </ul>
 113
 114 <hr>
 115 <a name="bridge"><h3>Bridge module</h3></a>
 116 <ul>
 117 <li><a href="https://github.com/kaizawa/bridge/tarball/master">bridge.tar.gz</a> (Last Update: 14 Dec 2009)
 118 <li><a href="http://github.com/kaizawa/bridge">Source</a><p>
 119
 120    After extracting bridge.tar.gz file, run './configure', 'make', and 'make install'.
 121    'brdg' and brdgadm will be built and installed on your system.<br>
 122    Where 'brdg' is a STREAMS module which enables briging 2 interfaces. And where
 123    'brdgadm' is a configuration command to add/delete bridge interfaces.
 124
 125 <pre>
 126 Usage: brdgadm [ -a interface | -d interface]
 127 Options:
 128    -a interface   : Add interface as port
 129    -d interface   : Delete interface from port list
 130    -l             : List all interfaces in port list
 131 </pre>
 132
 133 See following sample configuration.
 134
 135 <h4>Network configuration</h4>
 136
 137 <img src="./network_config.png"><br>
 138
 139 HostB is a router which is connected to 2 networks.
 140 By installing TAP and OpenVPN on HostB and HostC,
 141 I try to join HostC to Network1 through OpenVPN.<p>
 142
 143 <ol>
 144 <li> On HostB, install TAP driver and OpenVPN, and then
 145     configure it as bridging server using server-bridge
 146     option.
 147 <pre>
 148 -------------
 149 dev tap
 150 proto tcp-server
 151 server-bridge 10.0.0.90 255.0.0.0 10.0.0.10 10.0.0.30
 152 client-to-client
 153 ca /etc/openvpn/keys/ca.crt
 154 cert /etc/openvpn/keys/u1.crt
 155 key /etc/openvpn/keys/u1.key  # This file should be kept secret
 156 dh /etc/openvpn/keys/dh1024.pem
 157 --------------
 158 </pre>
 159     Then, run openvpn </li>
 160 <li>On HostB, make and install bridge module.
 161   <ol>
 162   <li>Extrace bridge.tar.gz
 163   <pre>
 164    # gunzip -c bridge.tar.gz | tar xvf -
 165   </pre>
 166   </li>
 167   <li>Make bridge moduel(brdg) and control command(brdgadm)
 168   <pre>
 169    # ./configure
 170    # make
 171    # make install
 172   </pre>
 173   </li>
 174   </ol> </li>
 175 <li>On HostB, setting up bridge.
 176   <pre>
 177    # /usr/local/bin/brdgadm -a tap0
 178    # /usr/local/bin/brdgadm -a hme1
 179   </pre>
 180
 181   where hme1 is a network interface connected with Network1.
 182   As a result, tap0 and hme1 is bridged.
 183   At this time, ifconfig looks like as below.
 184   <pre>
 185   hme0: flags=1000843&lt;UP,BROADCAST,RUNNING,MULTICAST,IPv4&gt; mtu 1500 index 2
 186        inet 172.29.73.90 netmask ffffff00 broadcast 172.29.73.255
 187        ether 8:0:20:91:a6:90
 188   hme1: flags=1000843&lt;UP,BROADCAST,RUNNING,MULTICAST,IPv4&gt; mtu 1500 index 4
 189        inet 10.0.0.90 netmask ff000000 broadcast 10.255.255.255
 190         ether 8:0:20:91:a6:90
 191   tap0: flags=1000842&lt;BROADCAST,RUNNING,MULTICAST,IPv4&gt; mtu 1500 index 5
 192        inet 0.0.0.0 netmask 0
 193        ether a:0:20:14:32:52
 194   </pre></li>
 195
 196 <li>On HostC, install TAP driver and openvpn, and
 197     configure it as a client.
 198    <pre>
 199 ------------
 200 remote HostB
 201 proto tcp-client
 202 dev tap
 203 client
 204 persist-tun
 205 ca /etc/openvpn/keys/ca.crt
 206 cert /etc/openvpn/keys/onnv01.crt
 207 key /etc/openvpn/keys/onnv01.key
 208 -----------
 209    </pre>
 210    Then, run openvpn.
 211    At this time, ifconfig on HostC looks like as below.
 212
 213    <pre>
 214    hme0: flags=1000843&lt;UP,BROADCAST,RUNNING,MULTICAST,IPv4&gt; mtu 1500 index 2
 215         inet 172.29.73.55 netmask ffffff00 broadcast 172.29.73.255
 216         ether 8:0:20:c6:69:c7
 217    tap0: flags=1000843&lt;UP,BROADCAST,RUNNING,MULTICAST,IPv4&gt; mtu 1500 index 4
 218         inet 10.0.0.10 netmask ff000000 broadcast 10.255.255.255
 219         ether a:0:20:53:71:52
 220    </pre></li>
 221 </ol>
 222
 223 Now, HostC joins Network1 via tap0 interface through openvpn.<P>
 224 <b>But, please note that there's some limitation.. HostC can't communicate with
 225 HostB using a bridged IP address on HostB.</b>
 226 I mean, ping 10.0.0.90 on HostC won't work. <p>
 227
 228 <img src="./brdg_issue_en.png">
 229
 230 <ol>
 231 <li>Ethernet packet from OpenVPN headed to HostB is passed to TAP driver.
 232 <li>TAP driver forwards packet to bridge module.
 233 <li>Bridge module forwards packet to hme driver as RAW data.
 234 <li>hme driver transfer the packet to the wire, but never forward it to IP module.
 235 </ol><p>
 236
 237 Of course, HostC can communicate with all the other hosts on Network1, but.. it can't
 238 communicate with bridged IP address of bridge server.<p>
 239
 240 One more note. Once openvpn running on HostB is terminated,
 241 bridge setting will be invalidated. So, after executing
 242 2nd openvpn on HostB, you need to re-setup the bridge again.<p>
 243
 244   First, you need to drop existing settings.
 245   <pre>
 246    # /usr/local/bin/brdgadm -d hme1
 247    # /usr/local/bin/brdgadm -d tap0
 248   </pre>
 249   Then, re-setup bridge.
 250   <pre>
 251    # /usr/local/bin/brdgadm -a hme1
 252    # /usr/local/bin/brdgadm -a tap0
 253   </pre>
 254 </ul>
 255
 256 <hr>
 257 <a name="tunctl"><h3>tunctl command for Solaris</h3></a>
 258 <ul>
 259 <li><a href="https://github.com/kaizawa/tunctl/tarball/master">tunctl.tar.gz (v0.1.0)</a> (Last Update: 27th Nov 2011)
 260 <li><a href="http://github.com/kaizawa/tunctl">Source</a><p>
 261   This is a Solaris version of tunctl command which was originally written by Jeff Dike.<br>
 262   The tunctl command enables administrator to preconfigure a TUN/TAP device.
 263   This command would be useful for testing, or for those who wants to use
 264   tun/tap interface just as a virtual interface.<br><br>
 265
 266   After extracting tuncntl.tar.gz file, run './configure', 'make', and 'make install'.<br>
 267   By default, tunctl command is installed in /usr/local/bin<br><br>
 268
 269   NOTE:<br>
 270   This Solaris version of tunctl command doesn't support the -u option,
 271    which enables administrator to specify an user who can use the interface.<br><br>
 272
 273   Example)<br>
 274   Create tap0 interface
 275 <pre>
 276    # /usr/local/bin/tunctl -t tap0
 277    Set 'tap0' persistent
 278    #
 279 </pre>
 280   Delete tap0 interface
 281 <pre>
 282    # /usr/local/bin/tunctl -d tap0
 283    #
 284 </pre>
 285 </pre>
 286
 287 </ul>
 288
 289
 290 <hr>
 291 <a name="test"><h3>Tested Solaris versioin</h3></a>
 292 I've tested on following Solaris version and platform.
 293
 294 <ul>
 295 <li>32 bit Solaris 9 on x86.
 296 <li>32 bit Solaris 9 on sparc.
 297 <li>64 bit Solaris 9 on sparc.
 298 <li>32 bit Solaris 10 on x86.
 299 <li>64 bit Solaris 10 on sparc.
 300 <li>64 bit Solaris 10 on x64.
 301 <li>32 bit OpenSolaris snv_101b on x86.
 302 <li>64 bit OpenSolaris snv_101b on sparc.
 303 <li>64 bit OpenSolaris snv_101b on x64.
 304 <li>32 bit Solaris 11 Express on x86.
 305 <li>32 bit OpenIndiana oi_148 on x86.
 306 <li>64 bit Solaris 11 Early Adoper svn_173 on x64.
 307 <li>64 bit Solaris 11 on x64.
 308 <li>64 bit Solaris 11 on sparc.
 309 </ul>
 310
 311 <hr>
 312
 313 <a name="change"><h3>Change log</h3></a>
 314
 315 <ul>
 316 <li>05/08/2006<br>
 317         <ul>
 318         <li>Modified tun_unitdata_req() to work on x86 Solaris 9
 319         </ul>
 320 <li>05/12/2006<br>
 321         <ul>
 322         <li>Added tun_generate_mac_addr() to generate MAC address for tap device.
 323         </ul>
 324 <li>10/09/2006<br>
 325         <ul>
 326         <li>Confirmed that the driver was able to work with OpenVPN 2.0.9.<br>
 327             And also confirmed that tun.c file included in OpenVPN 2.0.9 has not
 328             been changed. <br>
 329             So the above tun.c file can be compiled with OpenVPN 2.0.9 as well.
 330         </ul>
 331 <li>11/05/2006<br>
 332         <ul>
 333         <li>In tun_ioctl() of tap driver, reverted to original TUN/TAP driver's
 334             code which retrieves ppa from user program.
 335         <li>In open_tun() of openvpn, changed it to use I_STR ioctl command to
 336             pass ppa to tap driver. <br>
 337             This will allow openvpn to specify instance number using 'dev' option, like
 338             "dev tap7".
 339         </ul>
 340 <li>01/03/2007<br>
 341         <ul>
 342         <li>Added comments about bridge module.
 343         </ul>
 344 <li>02/21/2007<br>
 345         <ul>
 346         <li>Modified brdgadm.c file to make it to be able to handle e1000g.
 347         <li>Modified brdgadm.c file to make it to be able to handle instance number
 348         <li>Modified configure script of both bridge module and tun/tap driver to
 349             be able to build modules on x64 Solaris.
 350         </ul>
 351 <li>03/22/2007<br>
 352         <ul>
 353         <li>Removed unnecessary debug code from brdgadm.c.
 354         </ul>
 355 <li>06/25/2007<br>
 356         <ul>
 357         <li>Added "-mno-red-zone" compile option for amd64.
 358         </ul>
 359 <li>09/24/2007<br>
 360         <ul>
 361         <li>Modified Makefile.in for brdgadm command, so that it allows to specify
 362             installation directory by --prefix option of configure script.
 363         </ul>
 364 <li>12/07/2008<br>
 365         <ul>
 366         <li>Modified tun.c file of OpenVPN file to make it be able to be compiled with openvpn 2.1.
 367         </ul>
 368 <li>04/30/2009<br>
 369         <ul>
 370         <li>Modified Makefile.in and configure.in script to check whether ld is GNU ld or Solaris bundled ld command.
 371         <li>Modified configure.in script to be able to build 32bit module on 64bit environment using --disable-64bit.
 372         <li>Modified Makefile.in to be able to specify target directory using DESTDIR macro.
 373         </ul>
 374 <li>05/20/2009<br>
 375         <ul>
 376         <li>Modified configure.in and changed the way of checking GNU ld because latest OpenSolaris ld has --version option.
 377         <li>Modified openvpn patch file(tun.c) and make openvpn commnad won't fail because of failure of I_POP ioctl command.
 378         </ul>
 379 <li>06/07/2009<br>
 380         <ul>
 381         <li>Modified configure.in, Makefile.in and make it be able to build using Sun Studio Compiler.(Tested on Sun Studio 12)
 382         </ul>
 383 <li>09/14/2009<br>
 384         <ul>
 385         <li>Added -xmodel=kernel option for Sun Studio compiler on amd64 platform.</br>
 386             (Formerly loading the driver failed with relocation error)
 387         </ul>
 388 <li>11/16/2009<br>
 389         <ul>
 390         <li>Added ipv6 support to tun driver as required by <a href="http://www.infradead.org/openconnect.html">OpenConnect VPN Client</a><br>
 391         </ul>
 392 <li>11/18/2009<br>
 393         <ul>
 394         <li>Modified tun.c of OpenVPN 2.1_rc21 and set ipv6_explicitly_supported to true for Solaris.<br>
 395         </ul>
 396 <li>12/14/2009<br>
 397         <ul>
 398         <li>Added -xmodel=kernel option to configure script of bridge module for Sun Studio compiler on amd64 platform.
 399         </ul>
 400 <li>04/29/2010<br>
 401         <ul>
 402         <li>Merged chages on tun.c of OpenVPN 2.1.1.<br>
 403         </ul>
 404 <li>08/31/2010<br>
 405         <ul>
 406         <li>Merged chages on tun.c of OpenVPN 2.1.3.<br>
 407         </ul>
 408 <li>09/17/2010<br>
 409         <ul>
 410         <li>Moved all download files to github repository.
 411         </ul>
 412 <li>04/29/2011<br>
 413         <ul>
 414         <li>Tested on Oracle Solaris 11 Express and OpenIndiana 148.
 415         </ul>
 416 <li>06/11/2011<br>
 417         <ul>
 418         <li>Set default prefix for tun/tap driver, so that files would be copied to right directory.
 419         </ul>
 420 <li>09/19/2011<br>
 421         <ul>
 422         <li>brdgadm: replaced strncpy with strlcpy.
 423         </ul>
 424 <li>10/23/2011<br>
 425         <ul>
 426         <li>tuntap: Changed tun.c configure.in to be able to build on Solaris 11 EA (snv_173).<br>
 427             Because snv_173 doesn't have ddi_power kernel function and DDI_PM_SUSPEND macro.
 428         </ul>
 429 <li>11/16/2011<br>
 430         <ul>
 431         <li>tuntap: Changed configure.in to use uname -r for version checking instead of uname -v.
 432         </ul>
 433 <li>11/27/2011<br>
 434         <ul>
 435         <li>tunctl: Stopped using text file to store muxid, instead store muxid to ip module by SIOCSLIFMUXID ioctl command.
 436         </ul>
 437 <li>12/06/2011<br>
 438         <ul>
 439         <li>tuntap: Modified configure scrip to use -mcmodel=large for gcc-45. This enable driver compiled by gcc-45 to be loaded to the system without err(e.g relocation error: R_AMD64_32)
 440         </ul>
 441 <li>07/17/2012<br>
 442         <ul>
 443         <li>tuntap: Improved throughput perfomance by increasing q_hiwat of read side stream head queue.<br>
 444         </ul>
 445 <li>07/07/2013<br>
 446         <ul>
 447         <li>tuntap: Changed option for GNU ld, from elf_x86_64 to elf_x86_64_sol2
 448         <li>tuntap: Added test script
 449 </ul>
 450 <li>12/14/2014<br>
 451         <ul>
 452         <li>tunctl: Fixed to make tunctl bring tap interface up.
 453 </ul>
 454
 455 <hr>
 456
 457 <br>
 458 I wrote this just for fun. Since this has not been tested well, please DON'T
 459 install this on production system. Use this at your own risk.<br>
 460 But your advice or comment would be appreciated.
 461
 462 <p>
 463 <p>
 464 ---<br>
 465 Kazuyoshi Aizawa &lt;admin2@whiteboard.ne.jp&gt;<br>
 466 28th Apr 2006
 467 ---<br>
 468 This page and illustrations above were downloaded for packaging from
 469 <a href="http://www.whiteboard.ne.jp/~admin2/tuntap/">http://www.whiteboard.ne.jp/~admin2/tuntap/</a>
 470 on 19th Nov 2016 and mildly modified (removed ad scripts and added this footer).
 471 <hr>
 472
 473 </body>
 474 </html>