]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
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: | |
ca6bb5d7 DW |
42 | e.g. chmod 0666 /dev/net/tun |
43 | There's no harm in allowing the device to be accessible by non-root users, | |
44 | since CAP_NET_ADMIN is required for creating network devices or for | |
45 | connecting to network devices which aren't owned by the user in question. | |
46 | If you want to create persistent devices and give ownership of them to | |
47 | unprivileged users, then you need the /dev/net/tun device to be usable by | |
48 | those users. | |
1da177e4 LT |
49 | |
50 | Driver module autoloading | |
51 | ||
52 | Make sure that "Kernel module loader" - module auto-loading | |
53 | support is enabled in your kernel. The kernel should load it on | |
54 | first access. | |
55 | ||
56 | Manual loading | |
57 | insert the module by hand: | |
58 | modprobe tun | |
59 | ||
60 | If you do it the latter way, you have to load the module every time you | |
61 | need it, if you do it the other way it will be automatically loaded when | |
62 | /dev/net/tun is being opened. | |
63 | ||
64 | 3. Program interface | |
65 | 3.1 Network device allocation: | |
66 | ||
67 | char *dev should be the name of the device with a format string (e.g. | |
68 | "tun%d"), but (as far as I can see) this can be any valid network device name. | |
69 | Note that the character pointer becomes overwritten with the real device name | |
70 | (e.g. "tun0") | |
71 | ||
72 | #include <linux/if.h> | |
73 | #include <linux/if_tun.h> | |
74 | ||
75 | int tun_alloc(char *dev) | |
76 | { | |
77 | struct ifreq ifr; | |
78 | int fd, err; | |
79 | ||
80 | if( (fd = open("/dev/net/tun", O_RDWR)) < 0 ) | |
81 | return tun_alloc_old(dev); | |
82 | ||
83 | memset(&ifr, 0, sizeof(ifr)); | |
84 | ||
85 | /* Flags: IFF_TUN - TUN device (no Ethernet headers) | |
86 | * IFF_TAP - TAP device | |
87 | * | |
88 | * IFF_NO_PI - Do not provide packet information | |
89 | */ | |
90 | ifr.ifr_flags = IFF_TUN; | |
91 | if( *dev ) | |
92 | strncpy(ifr.ifr_name, dev, IFNAMSIZ); | |
93 | ||
94 | if( (err = ioctl(fd, TUNSETIFF, (void *) &ifr)) < 0 ){ | |
95 | close(fd); | |
96 | return err; | |
97 | } | |
98 | strcpy(dev, ifr.ifr_name); | |
99 | return fd; | |
100 | } | |
101 | ||
102 | 3.2 Frame format: | |
103 | If flag IFF_NO_PI is not set each frame format is: | |
104 | Flags [2 bytes] | |
105 | Proto [2 bytes] | |
106 | Raw protocol(IP, IPv6, etc) frame. | |
107 | ||
108 | Universal TUN/TAP device driver Frequently Asked Question. | |
109 | ||
110 | 1. What platforms are supported by TUN/TAP driver ? | |
111 | Currently driver has been written for 3 Unices: | |
112 | Linux kernels 2.2.x, 2.4.x | |
113 | FreeBSD 3.x, 4.x, 5.x | |
114 | Solaris 2.6, 7.0, 8.0 | |
115 | ||
116 | 2. What is TUN/TAP driver used for? | |
117 | As mentioned above, main purpose of TUN/TAP driver is tunneling. | |
118 | It is used by VTun (http://vtun.sourceforge.net). | |
119 | ||
120 | Another interesting application using TUN/TAP is pipsecd | |
121 | (http://perso.enst.fr/~beyssac/pipsec/), an userspace IPSec | |
122 | implementation that can use complete kernel routing (unlike FreeS/WAN). | |
123 | ||
124 | 3. How does Virtual network device actually work ? | |
125 | Virtual network device can be viewed as a simple Point-to-Point or | |
126 | Ethernet device, which instead of receiving packets from a physical | |
127 | media, receives them from user space program and instead of sending | |
128 | packets via physical media sends them to the user space program. | |
129 | ||
130 | Let's say that you configured IPX on the tap0, then whenever | |
131 | the kernel sends an IPX packet to tap0, it is passed to the application | |
132 | (VTun for example). The application encrypts, compresses and sends it to | |
133 | the other side over TCP or UDP. The application on the other side decompresses | |
134 | and decrypts the data received and writes the packet to the TAP device, | |
135 | the kernel handles the packet like it came from real physical device. | |
136 | ||
137 | 4. What is the difference between TUN driver and TAP driver? | |
138 | TUN works with IP frames. TAP works with Ethernet frames. | |
139 | ||
140 | This means that you have to read/write IP packets when you are using tun and | |
141 | ethernet frames when using tap. | |
142 | ||
143 | 5. What is the difference between BPF and TUN/TAP driver? | |
3d79c33b | 144 | BPF is an advanced packet filter. It can be attached to existing |
1da177e4 LT |
145 | network interface. It does not provide a virtual network interface. |
146 | A TUN/TAP driver does provide a virtual network interface and it is possible | |
147 | to attach BPF to this interface. | |
148 | ||
149 | 6. Does TAP driver support kernel Ethernet bridging? | |
150 | Yes. Linux and FreeBSD drivers support Ethernet bridging. |