i386/linux/linux-2.3.21/Documentation/networking/ethertap.txt

   1 Documentation on setup and use of EtherTap.
   2
   3 Contact Jay Schulist <Jay.Schulist@spacs.k12.wi.us> if you
   4 have questions or need futher assistance.
   5
   6 Introduction
   7 ============
   8
   9 Ethertap provides packet reception and transmission for user
  10 space programs. It can be viewed as a simple Ethernet device,
  11 which instead of receiving packets from a network wire, it receives
  12 them from user space.
  13
  14 Ethertap can be used for anything from AppleTalk to IPX to even
  15 building bridging tunnels. It also has many other general purpose
  16 uses.
  17
  18 Ethertap also can do ARP for you, although this is not enabled by
  19 default.
  20
  21 SetUp
  22 =====
  23
  24 First you will have to enable Ethertap in the kernel configuration.
  25 Then you will need to create any number of ethertap device files,
  26 /dev/tap0->/dev/tap15. This is done by the following command.
  27
  28 mknod /dev/tap* c 36 16  ( 17 18 19 20 for tap1,2,3,4...)
  29
  30 ** Replace * with the proper tap device number you need. **
  31
  32 Now with your kernel that has ethertap enabled, you will need
  33 to ifconfig /dev/tap* 192.168.1.1 (replace 192.168.1.1 with the
  34 proper IP number for your situation.)
  35
  36 If you want your Ethertap device to ARP for you would ifconfig
  37 the interface like this: ifconfig tap* 192.168.1.1 arp
  38
  39 Remember that you need to have a corresponding /dev/tap* file
  40 for each tap* device you need to ifconfig.
  41
  42 Now Ethertap should be ready to use.
  43
  44 Diagram of how Ethertap works. (Courtesy of Alan Cox)
  45 ====================================================
  46
  47 This is for a tunnel, but you should be able to
  48 get the general idea.
  49
  50         1.2.3.4 will be the router to the outside world
  51         1.2.3.5 our box
  52         2.0.0.1 our box (appletalk side)
  53         2.0.0.* a pile of macintoys
  54
  55
  56 [1.2.3.4]-------------1.2.3.5[Our Box]2.0.0.1---------> macs
  57
  58 The routing on our box would be
  59
  60                 ifconfig eth0 1.2.3.5 netmask 255.255.255.0 up
  61                 route add default gw 1.2.3.4
  62                 ifconfig tap0   2.0.0.1 netmask 255.255.255.0 up arp
  63                 (route add 2.0.0.0 netmask 255.255.255.0)
  64
  65 C code for a Simple program using an EtherTap device
  66 ====================================================
  67
  68 This code is just excerpts from a real program, so some parts are missing
  69 but the important stuff is below.
  70
  71 void main (void)
  72 {
  73         int TapDevice, eth_pkt_len = 0;
  74         unsigned char full_pkt_len[MAX_PKT_LEN];
  75
  76         TapDevice = open("/dev/tap0", O_RDWR);
  77         if(TapDevice < 0)
  78         {
  79                 perror("Error opening device");
  80                 exit(1);
  81         }
  82
  83         write(TapDevice, full_packet, eth_pkt_len);
  84
  85         close(TapDevice);
  86
  87         return;
  88 }