Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | Universal TUN/TAP device driver. |
| 2 | Copyright (C) 1999-2000 Maxim Krasnyansky <max_mk@yahoo.com> |
| 3 | |
| 4 | Linux, Solaris drivers |
| 5 | Copyright (C) 1999-2000 Maxim Krasnyansky <max_mk@yahoo.com> |
| 6 | |
| 7 | FreeBSD TAP driver |
| 8 | Copyright (c) 1999-2000 Maksim Yevmenkin <m_evmenkin@yahoo.com> |
| 9 | |
| 10 | Revision of this document 2002 by Florian Thiel <florian.thiel@gmx.net> |
| 11 | |
| 12 | 1. Description |
| 13 | TUN/TAP provides packet reception and transmission for user space programs. |
| 14 | It can be seen as a simple Point-to-Point or Ethernet device, which, |
| 15 | instead of receiving packets from physical media, receives them from |
| 16 | user space program and instead of sending packets via physical media |
| 17 | writes them to the user space program. |
| 18 | |
| 19 | In order to use the driver a program has to open /dev/net/tun and issue a |
| 20 | corresponding ioctl() to register a network device with the kernel. A network |
| 21 | device will appear as tunXX or tapXX, depending on the options chosen. When |
| 22 | the program closes the file descriptor, the network device and all |
| 23 | corresponding routes will disappear. |
| 24 | |
| 25 | Depending on the type of device chosen the userspace program has to read/write |
| 26 | IP packets (with tun) or ethernet frames (with tap). Which one is being used |
| 27 | depends on the flags given with the ioctl(). |
| 28 | |
| 29 | The package from http://vtun.sourceforge.net/tun contains two simple examples |
| 30 | for how to use tun and tap devices. Both programs work like a bridge between |
| 31 | two network interfaces. |
| 32 | br_select.c - bridge based on select system call. |
| 33 | br_sigio.c - bridge based on async io and SIGIO signal. |
| 34 | However, the best example is VTun http://vtun.sourceforge.net :)) |
| 35 | |
| 36 | 2. Configuration |
| 37 | Create device node: |
| 38 | mkdir /dev/net (if it doesn't exist already) |
| 39 | mknod /dev/net/tun c 10 200 |
| 40 | |
| 41 | Set permissions: |
| 42 | e.g. chmod 0700 /dev/net/tun |
| 43 | if you want the device only accessible by root. Giving regular users the |
| 44 | right to assign network devices is NOT a good idea. Users could assign |
| 45 | bogus network interfaces to trick firewalls or administrators. |
| 46 | |
| 47 | Driver module autoloading |
| 48 | |
| 49 | Make sure that "Kernel module loader" - module auto-loading |
| 50 | support is enabled in your kernel. The kernel should load it on |
| 51 | first access. |
| 52 | |
| 53 | Manual loading |
| 54 | insert the module by hand: |
| 55 | modprobe tun |
| 56 | |
| 57 | If you do it the latter way, you have to load the module every time you |
| 58 | need it, if you do it the other way it will be automatically loaded when |
| 59 | /dev/net/tun is being opened. |
| 60 | |
| 61 | 3. Program interface |
| 62 | 3.1 Network device allocation: |
| 63 | |
| 64 | char *dev should be the name of the device with a format string (e.g. |
| 65 | "tun%d"), but (as far as I can see) this can be any valid network device name. |
| 66 | Note that the character pointer becomes overwritten with the real device name |
| 67 | (e.g. "tun0") |
| 68 | |
| 69 | #include <linux/if.h> |
| 70 | #include <linux/if_tun.h> |
| 71 | |
| 72 | int tun_alloc(char *dev) |
| 73 | { |
| 74 | struct ifreq ifr; |
| 75 | int fd, err; |
| 76 | |
| 77 | if( (fd = open("/dev/net/tun", O_RDWR)) < 0 ) |
| 78 | return tun_alloc_old(dev); |
| 79 | |
| 80 | memset(&ifr, 0, sizeof(ifr)); |
| 81 | |
| 82 | /* Flags: IFF_TUN - TUN device (no Ethernet headers) |
| 83 | * IFF_TAP - TAP device |
| 84 | * |
| 85 | * IFF_NO_PI - Do not provide packet information |
| 86 | */ |
| 87 | ifr.ifr_flags = IFF_TUN; |
| 88 | if( *dev ) |
| 89 | strncpy(ifr.ifr_name, dev, IFNAMSIZ); |
| 90 | |
| 91 | if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){ |
| 92 | close(fd); |
| 93 | return err; |
| 94 | } |
| 95 | strcpy(dev, ifr.ifr_name); |
| 96 | return fd; |
| 97 | } |
| 98 | |
| 99 | 3.2 Frame format: |
| 100 | If flag IFF_NO_PI is not set each frame format is: |
| 101 | Flags [2 bytes] |
| 102 | Proto [2 bytes] |
| 103 | Raw protocol(IP, IPv6, etc) frame. |
| 104 | |
| 105 | Universal TUN/TAP device driver Frequently Asked Question. |
| 106 | |
| 107 | 1. What platforms are supported by TUN/TAP driver ? |
| 108 | Currently driver has been written for 3 Unices: |
| 109 | Linux kernels 2.2.x, 2.4.x |
| 110 | FreeBSD 3.x, 4.x, 5.x |
| 111 | Solaris 2.6, 7.0, 8.0 |
| 112 | |
| 113 | 2. What is TUN/TAP driver used for? |
| 114 | As mentioned above, main purpose of TUN/TAP driver is tunneling. |
| 115 | It is used by VTun (http://vtun.sourceforge.net). |
| 116 | |
| 117 | Another interesting application using TUN/TAP is pipsecd |
| 118 | (http://perso.enst.fr/~beyssac/pipsec/), an userspace IPSec |
| 119 | implementation that can use complete kernel routing (unlike FreeS/WAN). |
| 120 | |
| 121 | 3. How does Virtual network device actually work ? |
| 122 | Virtual network device can be viewed as a simple Point-to-Point or |
| 123 | Ethernet device, which instead of receiving packets from a physical |
| 124 | media, receives them from user space program and instead of sending |
| 125 | packets via physical media sends them to the user space program. |
| 126 | |
| 127 | Let's say that you configured IPX on the tap0, then whenever |
| 128 | the kernel sends an IPX packet to tap0, it is passed to the application |
| 129 | (VTun for example). The application encrypts, compresses and sends it to |
| 130 | the other side over TCP or UDP. The application on the other side decompresses |
| 131 | and decrypts the data received and writes the packet to the TAP device, |
| 132 | the kernel handles the packet like it came from real physical device. |
| 133 | |
| 134 | 4. What is the difference between TUN driver and TAP driver? |
| 135 | TUN works with IP frames. TAP works with Ethernet frames. |
| 136 | |
| 137 | This means that you have to read/write IP packets when you are using tun and |
| 138 | ethernet frames when using tap. |
| 139 | |
| 140 | 5. What is the difference between BPF and TUN/TAP driver? |
| 141 | BFP is an advanced packet filter. It can be attached to existing |
| 142 | network interface. It does not provide a virtual network interface. |
| 143 | A TUN/TAP driver does provide a virtual network interface and it is possible |
| 144 | to attach BPF to this interface. |
| 145 | |
| 146 | 6. Does TAP driver support kernel Ethernet bridging? |
| 147 | Yes. Linux and FreeBSD drivers support Ethernet bridging. |