1# Copyright (c) 2013 The Chromium OS Authors. All rights reserved. 2# Use of this source code is governed by a BSD-style license that can be 3# found in the LICENSE file. 4 5DOC = """\ 6lansim is a LAN simulator that runs over a TAP network interface and 7allows to simulate network traffic on that interface from Python code. 8 9A TAP interface is a virtual network kernel device that acts as any 10other network interface, except that instead of sending and receiving 11the traffic through a hardware interface it allows a given program to 12handle that traffic through a socket. It is essentially a 13bi-directional pipe where one side is a network interface and the 14other side is a socket on a program. 15 16The lansim Simulator class allows a Python function to attend all the 17outbound traffic matching certain rules and take an action over that 18like send back a packet to this interface. The kernel network stack 19will see this packet as an inbound packet from the fake interface. 20These actions can also be time driven, like a simulation timeout or 21send a ping packet every second. 22 23This simulator is useful on situations where you can't fake a network 24service using the normal kernel network stack. For example, if you 25need to fake a network of several hosts publishing services via mDNS 26with multicast you can write those services using this simulator but 27it's more complicated to do the same using the system's network stack 28since an outbound multicast packet will be sent out on the real 29interface. 30 31The Simulator class requires a TAP network interface and allows other 32Python classes to subscribe to its traffic. The TAP interface needs to 33be up when the Simulator runs. 34 35For example, to create a tap interface you can do the following: 36 37 tap = tuntap.TunTap(tuntap.IFF_TAP, name="faketap") 38 print "Interface running on", tap.name 39 40This will create a TAP interface with a name like "faketap0". You can 41then configure it manually, or just bring it up without an IP address 42if you have a Python class implementing a fake DHCP server to 43configure it later. To set the IP address manually, you can use any 44system command like "ip" or "ifconfig", or from Python in this way: 45 46 tap.set_addr("192.168.0.123") 47 tap.up() 48 49A very simple example of the usage of this simulator is the 50following, where three hosts are created on the faketap0 interface 51and will respond to ARP requests. Running the command 52"arping -I faketap0 192.168.0.4" will show two responses for that 53given IP address: 54 55 simu = simulator.SimulatorThread(tap) 56 57 host_a = host.SimpleHost(simu, '12:34:56:78:90:AB', '192.168.0.3') 58 host_b = host.SimpleHost(simu, '12:34:56:78:90:CD', '192.168.0.4') 59 host_c = host.SimpleHost(simu, '12:34:56:78:90:EF', '192.168.0.4') 60 61 simu.start() # Run the thread. 62 print "Press enter to stop the simulation." 63 raw_input() 64 simu.stop() 65 simu.join() 66""" 67 68job.setup_dep(['lansim']) 69