Home | History | Annotate | Download | only in lansim 
      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 
      5 DOC = """\
      6 lansim is a LAN simulator that runs over a TAP network interface and
      7 allows to simulate network traffic on that interface from Python code.
      8 
      9 A TAP interface is a virtual network kernel device that acts as any
     10 other network interface, except that instead of sending and receiving
     11 the traffic through a hardware interface it allows a given program to
     12 handle that traffic through a socket. It is essentially a
     13 bi-directional pipe where one side is a network interface and the
     14 other side is a socket on a program.
     15 
     16 The lansim Simulator class allows a Python function to attend all the
     17 outbound traffic matching certain rules and take an action over that
     18 like send back a packet to this interface. The kernel network stack
     19 will see this packet as an inbound packet from the fake interface.
     20 These actions can also be time driven, like a simulation timeout or
     21 send a ping packet every second.
     22 
     23 This simulator is useful on situations where you can't fake a network
     24 service using the normal kernel network stack. For example, if you
     25 need to fake a network of several hosts publishing services via mDNS
     26 with multicast you can write those services using this simulator but
     27 it's more complicated to do the same using the system's network stack
     28 since an outbound multicast packet will be sent out on the real
     29 interface.
     30 
     31 The Simulator class requires a TAP network interface and allows other
     32 Python classes to subscribe to its traffic. The TAP interface needs to
     33 be up when the Simulator runs.
     34 
     35 For 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 
     40 This will create a TAP interface with a name like "faketap0". You can
     41 then configure it manually, or just bring it up without an IP address
     42 if you have a Python class implementing a fake DHCP server to
     43 configure it later. To set the IP address manually, you can use any
     44 system command like "ip" or "ifconfig", or from Python in this way:
     45 
     46     tap.set_addr("192.168.0.123")
     47     tap.up()
     48 
     49 A very simple example of the usage of this simulator is the
     50 following, where three hosts are created on the faketap0 interface
     51 and will respond to ARP requests. Running the command
     52 "arping -I faketap0 192.168.0.4" will show two responses for that
     53 given 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 
     68 job.setup_dep(['lansim'])
     69