tuntap/README

   1
   2 tun/tap driver for Mac OS X
   3 ===========================
   4
   5 This is an experimental IP tunnel/ethertap driver for Mac OS X/Darwin. It
   6 provides /dev/tunX and /dev/tapX devices. The maximum number of devices can be
   7 configured at compile time, it is currently set to 16. That should be enough in
   8 most cases.
   9
  10 The driver ships as two kernel extensions, one for tap and one for tun. They are
  11 located in /Library/Extensions and can also be loaded and unloaded by hand. If
  12 you install the startup item, the system will load them automatically at
  13 startup (tun and tap startup items get installed in /Library/StartupItems).
  14
  15 Operation & Programming notes
  16 =============================
  17
  18 tapX are ethertap devices which provide an interface to the kernel's ethernet
  19 layer. Packets can be read from and written to the /dev/tapX character devices
  20 one at a time (same name as the interface that shows up in ifconfig).
  21
  22 tunX are IP tunnel devices. These can be used to exchange IP packets with the
  23 kernel. You will get single packets for each read() and should write() packets
  24 one at a time to /dev/tunX.
  25
  26 There are some special ioctls with the tun devices that allow you to have them
  27 prepend the address family of the packet when reading it from /dev/tunX. Using
  28 this mode the driver also expects you put this 4-byte address family field
  29 (network byte order) in front of the packets you write to /dev/tunX.
  30
  31 Here are the ioctls to setup up address prepending mode (for convenience there
  32 also is a header called tun_ioctls.h in the source package that you can use)
  33 Set the int argument to one if you want to have AF prepending, use 0 if you want
  34 to switch it off.
  35
  36 #define TUNSIFHEAD  _IOW('t', 96, int)
  37 #define TUNGIFHEAD  _IOR('t', 97, int)
  38
  39 Prepending mode is off by default. Currently it is not recommended to switch the
  40 mode while packets are in flight on the device.
  41
  42 The character devices are always visible in the filesystem as /dev/tunX and
  43 /dev/tapX. The number of available character devices is a compile time constant
  44 and is currently fixed to 16. Each character devices is associated with a
  45 network interface of the same name. The network interfaces are only created when
  46 the corresponding character device is opened by a program and will be removed
  47 when the character device is closed.
  48
  49 The character devices currently provide a pretty minimal interface. Whole
  50 packets are read and written using a singe read/write call. File descriptors
  51 opened on the devices can also be select()ed and support O_NONBLOCK.
  52 Asynchronous i/o and some ioctls are currently unimplemented, but implementing
  53 them shouldn't be very hard. Do it yourself or contact me if you can't live
  54 without.
  55
  56 There is another limitation imposed by the Darwin 8 kernel. It concerns the
  57 poll() system call; Darwin currently does *not* support that for (character)
  58 devices. Use select() instead.
  59
  60 The interfaces can be configured using ifconfig, the tap devices also support
  61 setting the MAC address to be used. Both tun and tap should be ready for IPv6.
  62 Just setup addresses and routing as you would do with other interfaces.
  63
  64 Please contact me if you find any bugs or have suggestions.
  65
  66 Enjoy!
  67
  68 Mattias
  69 <mattias.nissler@gmx.de>
  70
  71
  72 Uninstalling
  73 ============
  74
  75 The installer packages for OS X currently don't have support for uninstall as
  76 the installer doesn't provide it. Remove the following directories if you want
  77 to completely remove the files installed:
  78
  79 /Library/Extensions/tap.kext
  80 /Library/Extensions/tun.kext
  81 /Library/StartupItems/tap
  82 /Library/StartupItems/tun
  83
  84 Unload the the kernel extensions or reboot and you're done.
  85