A bridge to make it appear that a real host process is connected to an ns-3 net device. More...

#include <tap-bridge.h>

Inheritance diagram for ns3::TapBridge:

Public Types
enum	Mode { ILLEGAL, CONFIGURE_LOCAL, USE_LOCAL, USE_BRIDGE }

Public Types inherited from ns3::NetDevice
enum	PacketType { PACKET_HOST = 1, NS3_PACKET_HOST = PACKET_HOST, PACKET_BROADCAST, NS3_PACKET_BROADCAST = PACKET_BROADCAST, PACKET_MULTICAST, NS3_PACKET_MULTICAST = PACKET_MULTICAST, PACKET_OTHERHOST, NS3_PACKET_OTHERHOST = PACKET_OTHERHOST }

typedef Callback< bool, Ptr < NetDevice >, Ptr< const Packet >, uint16_t, const Address &, const Address &, enum PacketType >	PromiscReceiveCallback

typedef Callback< bool, Ptr < NetDevice >, Ptr< const Packet >, uint16_t, const Address & >	ReceiveCallback

Public Member Functions
virtual void	AddLinkChangeCallback (Callback< void > callback)

virtual Address	GetAddress (void) const

Ptr< NetDevice >	GetBridgedNetDevice (void)
	Get the bridged net device. More...

virtual Address	GetBroadcast (void) const

virtual Ptr< Channel >	GetChannel (void) const

virtual uint32_t	GetIfIndex (void) const

TapBridge::Mode	GetMode (void)

virtual uint16_t	GetMtu (void) const

virtual Address	GetMulticast (Ipv4Address multicastGroup) const
	Make and return a MAC multicast address using the provided multicast group. More...

virtual Address	GetMulticast (Ipv6Address addr) const
	Get the MAC multicast address corresponding to the IPv6 address provided. More...

virtual Ptr< Node >	GetNode (void) const

virtual bool	IsBridge (void) const
	Return true if the net device is acting as a bridge. More...

virtual bool	IsBroadcast (void) const

virtual bool	IsLinkUp (void) const

virtual bool	IsMulticast (void) const

virtual bool	IsPointToPoint (void) const
	Return true if the net device is on a point-to-point link. More...

virtual bool	NeedsArp (void) const

virtual bool	Send (Ptr< Packet > packet, const Address &dest, uint16_t protocolNumber)

virtual bool	SendFrom (Ptr< Packet > packet, const Address &source, const Address &dest, uint16_t protocolNumber)

virtual void	SetAddress (Address address)

void	SetBridgedNetDevice (Ptr< NetDevice > bridgedDevice)
	Set the ns-3 net device to bridge. More...

virtual void	SetIfIndex (const uint32_t index)

void	SetMode (TapBridge::Mode mode)

virtual bool	SetMtu (const uint16_t mtu)

virtual void	SetNode (Ptr< Node > node)

virtual void	SetPromiscReceiveCallback (NetDevice::PromiscReceiveCallback cb)

virtual void	SetReceiveCallback (NetDevice::ReceiveCallback cb)

void	Start (Time tStart)
	Set a start time for the device. More...

void	Stop (Time tStop)

virtual bool	SupportsSendFrom () const

Public Member Functions inherited from ns3::Object
void	AggregateObject (Ptr< Object > other)

void	Dispose (void)

AggregateIterator	GetAggregateIterator (void) const

virtual TypeId	GetInstanceTypeId (void) const

template<typename T >
Ptr< T >	GetObject (void) const

template<typename T >
Ptr< T >	GetObject (TypeId tid) const

void	Initialize (void)

Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
	SimpleRefCount (const SimpleRefCount &o)

uint32_t	GetReferenceCount (void) const

SimpleRefCount &	operator= (const SimpleRefCount &o)

void	Ref (void) const

void	Unref (void) const

Public Member Functions inherited from ns3::ObjectBase
void	GetAttribute (std::string name, AttributeValue &value) const

bool	GetAttributeFailSafe (std::string name, AttributeValue &attribute) const

void	SetAttribute (std::string name, const AttributeValue &value)

bool	SetAttributeFailSafe (std::string name, const AttributeValue &value)

bool	TraceConnect (std::string name, std::string context, const CallbackBase &cb)

bool	TraceConnectWithoutContext (std::string name, const CallbackBase &cb)

bool	TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)

bool	TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)

Static Public Member Functions
static TypeId	GetTypeId (void)

Static Public Member Functions inherited from ns3::NetDevice
static TypeId	GetTypeId (void)

Static Public Member Functions inherited from ns3::Object
static TypeId	GetTypeId (void)

Static Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
static void	Cleanup (void)

Static Public Member Functions inherited from ns3::ObjectBase
static TypeId	GetTypeId (void)

Protected Member Functions
bool	DiscardFromBridgedDevice (Ptr< NetDevice > device, Ptr< const Packet > packet, uint16_t protocol, Address const &src)

virtual void	DoDispose (void)

bool	ReceiveFromBridgedDevice (Ptr< NetDevice > device, Ptr< const Packet > packet, uint16_t protocol, Address const &src, Address const &dst, PacketType packetType)

Protected Member Functions inherited from ns3::Object
	Object (const Object &o)

virtual void	DoInitialize (void)

virtual void	NotifyNewAggregate (void)

Protected Member Functions inherited from ns3::ObjectBase
void	ConstructSelf (const AttributeConstructionList &attributes)

virtual void	NotifyConstructionCompleted (void)

Private Member Functions
void	CreateTap (void)

Ptr< Packet >	Filter (Ptr< Packet > packet, Address src, Address dst, uint16_t *type)

void	ForwardToBridgedDevice (uint8_t *buf, ssize_t len)

void	ReadCallback (uint8_t *buf, ssize_t len)

void	StartTapDevice (void)

void	StopTapDevice (void)

Private Attributes
Mac48Address	m_address

Ptr< NetDevice >	m_bridgedDevice

Ptr< TapBridgeFdReader >	m_fdReader

uint32_t	m_ifIndex

Mode	m_mode

uint16_t	m_mtu

Ptr< Node >	m_node

uint32_t	m_nodeId

bool	m_ns3AddressRewritten

uint8_t *	m_packetBuffer

NetDevice::PromiscReceiveCallback	m_promiscRxCallback

NetDevice::ReceiveCallback	m_rxCallback

int	m_sock

EventId	m_startEvent

EventId	m_stopEvent

std::string	m_tapDeviceName

Ipv4Address	m_tapGateway

Ipv4Address	m_tapIp

Mac48Address	m_tapMac

Ipv4Mask	m_tapNetmask

Time	m_tStart

Time	m_tStop

Detailed Description

A bridge to make it appear that a real host process is connected to an ns-3 net device.

The Tap Bridge lives in a kind of a gray world somewhere between a Linux host and an ns-3 bridge device. From the Linux perspective, this code appears as the user mode handler for a Tap net device. That is, when the Linux host writes to a /dev/tap device (that is either manually or automatically created depending on basic operating mode – more on this later), the write is redirected into the TapBridge that lives in the ns-3 world; and from this perspective, becomes a read. In other words, a Linux process writes a packet to a tap device and this packet is redirected to an ns-3 process where it is received by the TapBridge as a result of a read operation there. The TapBridge then sends the packet to the ns-3 net device to which it is bridged. In the other direction, a packet received by an ns-3 net device is bridged to the TapBridge (it appears via a callback from that net device. The TapBridge then takes that packet and writes it back to the host using the Linux TAP mechanism. This write to the device will then appear to the Linux host as if a packet has arrived on its device.

The upshot is that the Tap Bridge appears to bridge a tap device on a Linux host in the "real world" to an ns-3 net device in the simulation and make is appear that a ns-3 net device is actually installed in the Linux host. In order to do this on the ns-3 side, we need a "ghost node" in the simulation to hold the bridged ns-3 net device and the TapBridge. This node should not actually do anything else in the simulation since its job is simply to make the net device appear in Linux. This is not just arbitrary policy, it is because:

Bits sent to the Tap Bridge from higher layers in the ghost node (using the TapBridge Send() method) are completely ignored. The Tap Bridge is not, itself, connected to any network, neither in Linux nor in ns-3;
The bridged ns-3 net device is has had its receive callback disconnected from the ns-3 node and reconnected to the Tap Bridge. All data received by a bridged device will be sent to the Linux host and will not be received by the node. From the perspective of the ghost node, you can send over this device but you cannot ever receive.

Of course, if you understand all of the issues you can take control of your own destiny and do whatever you want – we do not actively prevent you from using the ghost node for anything you decide. You will be able to perform typical ns-3 operations on the ghost node if you so desire. The internet stack, for example, must be there and functional on that node in order to participate in IP address assignment and global routing. However, as mentioned above, interfaces talking any Tap Bridge or associated bridged net devices will not work completely. If you understand exactly what you are doing, you can set up other interfaces and devices on the ghost node and use them; or take advantage of the operational send side of the bridged devices to create traffic generators. We generally recommend that you treat this node as a ghost of the Linux host and leave it to itself, though.

Config Paths

ns3::TapBridge is accessible through the following paths with Config::Set and Config::Connect:

/NodeList/[i]/DeviceList/[i]/$ns3::TapBridge

Attributes

Mtu: The MAC-level Maximum Transmission Unit
- Set with class: ns3::UintegerValue
- Underlying type: uint16_t 0:65535
- Initial value: 0
- Flags: construct write read
DeviceName: The name of the tap device to create.
- Set with class: StringValue
- Underlying type: std::string
- Initial value:
- Flags: construct write read
Gateway: The IP address of the default gateway to assign to the host machine, when in ConfigureLocal mode.
- Set with class: Ipv4AddressValue
- Underlying type: Ipv4Address
- Initial value: 255.255.255.255
- Flags: construct write read
IpAddress: The IP address to assign to the tap device, when in ConfigureLocal mode. This address will override the discovered IP address of the simulated device.
- Set with class: Ipv4AddressValue
- Underlying type: Ipv4Address
- Initial value: 255.255.255.255
- Flags: construct write read
MacAddress: The MAC address to assign to the tap device, when in ConfigureLocal mode. This address will override the discovered MAC address of the simulated device.
- Set with class: Mac48AddressValue
- Underlying type: Mac48Address
- Initial value: ff:ff:ff:ff:ff:ff
- Flags: construct write read
Netmask: The network mask to assign to the tap device, when in ConfigureLocal mode. This address will override the discovered MAC address of the simulated device.
- Set with class: Ipv4MaskValue
- Underlying type: Ipv4Mask
- Initial value: 255.255.255.255
- Flags: construct write read
Start: The simulation time at which to spin up the tap device read thread.
- Set with class: TimeValue
- Underlying type: Time
- Initial value: +0.0ns
- Flags: construct write read
Stop: The simulation time at which to tear down the tap device read thread.
- Set with class: TimeValue
- Underlying type: Time
- Initial value: +0.0ns
- Flags: construct write read
Mode: The operating and configuration mode to use.
- Set with class: ns3::EnumValue
- Underlying type: ConfigureLocal|UseLocal|UseBridge
- Initial value: UseLocal
- Flags: construct write

No TraceSources are defined for this type.

Definition at line 103 of file tap-bridge.h.

Member Enumeration Documentation

enum ns3::TapBridge::Mode

Enumeration of the operating modes supported in the class.

Enumerator
ILLEGAL	mode not set
CONFIGURE_LOCAL	ns-3 creates and configures tap device
USE_LOCAL	ns-3 uses a pre-created tap, without configuring it
USE_BRIDGE	ns-3 uses a pre-created tap, and bridges to a bridging net device

Definition at line 112 of file tap-bridge.h.

Member Function Documentation

void ns3::TapBridge::AddLinkChangeCallback ( Callback< void > callback )

virtual

Parameters

callback the callback to invoke

Add a callback invoked whenever the link status changes to UP. This callback is typically used by the IP/ARP layer to flush the ARP cache and by IPv6 stack to flush NDISC cache whenever the link goes up.

packet	The packet we received from the host, and which we need to check.
src	A pointer to the data structure that will get the source MAC address of the packet (extracted from the packet Ethernet header).
dst	A pointer to the data structure that will get the destination MAC address of the packet (extracted from the packet Ethernet header).
type	A pointer to the variable that will get the packet type from either the Ethernet header in the case of type interpretation (DIX framing) or from the 802.2 LLC header in the case of length interpretation (802.3 framing).

packet	packet sent from above down to Network Device
dest	mac address of the destination (already resolved)
protocolNumber	identifies the type of payload contained in this packet. Used to call the right L3Protocol when the packet is received.

packet	packet sent from above down to Network Device
source	source mac address (so called "MAC spoofing")
dest	mac address of the destination (already resolved)
protocolNumber	identifies the type of payload contained in this packet. Used to call the right L3Protocol when the packet is received.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Config Paths

Attributes

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation