blob: ec3d109d787a42ca07f3ef60e94d8fcb888e6a2f [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Universal TUN/TAP device driver.
2Copyright (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
121. 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
362. 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
613. 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
105Universal TUN/TAP device driver Frequently Asked Question.
106
1071. What platforms are supported by TUN/TAP driver ?
108Currently 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
1132. What is TUN/TAP driver used for?
114As mentioned above, main purpose of TUN/TAP driver is tunneling.
115It is used by VTun (http://vtun.sourceforge.net).
116
117Another interesting application using TUN/TAP is pipsecd
118(http://perso.enst.fr/~beyssac/pipsec/), an userspace IPSec
119implementation that can use complete kernel routing (unlike FreeS/WAN).
120
1213. How does Virtual network device actually work ?
122Virtual network device can be viewed as a simple Point-to-Point or
123Ethernet device, which instead of receiving packets from a physical
124media, receives them from user space program and instead of sending
125packets via physical media sends them to the user space program.
126
127Let's say that you configured IPX on the tap0, then whenever
128the 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
130the other side over TCP or UDP. The application on the other side decompresses
131and decrypts the data received and writes the packet to the TAP device,
132the kernel handles the packet like it came from real physical device.
133
1344. What is the difference between TUN driver and TAP driver?
135TUN works with IP frames. TAP works with Ethernet frames.
136
137This means that you have to read/write IP packets when you are using tun and
138ethernet frames when using tap.
139
1405. What is the difference between BPF and TUN/TAP driver?
141BFP is an advanced packet filter. It can be attached to existing
142network interface. It does not provide a virtual network interface.
143A TUN/TAP driver does provide a virtual network interface and it is possible
144to attach BPF to this interface.
145
1466. Does TAP driver support kernel Ethernet bridging?
147Yes. Linux and FreeBSD drivers support Ethernet bridging.