ExtInterface

Package: inet.emulation.common

ExtInterface

compound module

A base for external network interfaces, network interface modules that connect the simulation to the network stack of the host OS.

Each external interface module is associated with a specific network device on the host OS. The host OS device is identified by the "namespace" and "device" parameters. The "namespace" parameter is optional; when empty, the default namespace is used.

External interfaces can be mentally visualized as composed of an upper and a lower part, one of which is the host OS device and the other is part of the simulation. Therefore, there are two types of external interfaces, which are also reflected in their names:

  • In ExtLower interfaces, the lower part is a host OS device, and the upper part is in the simulation. Therefore, an ExtLower interface module has upperLayerIn and upperLayerOut gates for connecting to the upper layers. The device is typically a "veth" (virtual Ethernet) device. (Using real interfaces like "eth0" is also possible, but it needs special care to prevent incoming packets from being replied to by both the simulation and the kernel or other processes on the host OS.)
  • In ExtUpper interfaces, the upper part is a host OS device, and the lower part is the simulated one. Therefore, an ExtUpper interface module typically has gates for connecting to the simulated network. The device is typically a "tap" (virtual TUN/TAP) device, which allows the interception of the traffic of the host OS and routing them into the simulation.

ExtLower interfaces are in general useful for connecting simulated apps to a real network, while ExtUpper interfaces are suitable for running a real networked application over a simulated network.

pcapRecorder[numPcapRecorders] : PcapRecorder Records PCAP traces of frames sent/received by other modules within the same host. Source: pcapRecorder[numPcapRecorders]: PcapRecorder { parameters: moduleNamePatterns = ".^"; @display("p=100,100;is=s"); } clock : like IClock IClock: Interface for clock models. Source: clock: <default("")> like IClock if typename != "" { parameters: @display("p=100,200;is=s"); }

Inheritance diagram

The following diagram shows inheritance relationships for this type. Unresolved types are missing from the diagram.

Known subclasses

Name Type Description
ExtLowerEthernetInterface compound module

Provides an Ethernet network interface suitable for emulation. The lower part of the network interface is realized in the real world using a real Ethernet socket of the host computer which is running the simulation.
ExtUpperEthernetInterface compound module

Provides an Ethernet network interface suitable for emulation. The upper part of the network interface is realized in the real world using a real TAP device of the host computer which is running the simulation.
ExtUpperIeee80211Interface compound module

Provides an IEEE 802.11 network interface suitable for emulation. The upper part of the network interface is realized in the real world using a real TAP device of the host computer which is running the simulation.

Extends

Name Type Description
NetworkInterface compound module

Serves as the base module for all network interfaces.

Parameters

Name Type Default value Description
displayStringTextFormat string "%a (%i)\n%m"

Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
recordPcap bool false
numPcapRecorders int recordPcap ? 1 : 0
isWireless bool false
interfaceTableModule string

Module path of the interface table module
device string

Name of the attached OS device (e.g. tap0, veth0, etc.)
namespace string ""

Name of the OS network namespace (optional)
copyConfiguration string ""

Copy interface configuration such as MAC address, IP address, and MTU from/to the external interface.
address string "auto"
broadcast bool true
multicast bool true
pointToPoint bool false
mtu int 4470B

Properties

Name Value Description
class ExtInterface
networkInterface
lifecycleSupport
display i=block/ifcard

Gates

Name Direction Size Description
upperLayerIn input
upperLayerOut output

Signals

Name Type Unit Description
packetDropped inet::Packet

Statistics

Name Title Source Record Unit Interpolation Mode Description
packetDropInterfaceDown packet drops: interface down packetDropReasonIsInterfaceDown(packetDropped) count, sum(packetBytes), vector(packetBytes) none
packetDropNoCarrier packet drops: no carrier packetDropReasonIsNoCarrier(packetDropped) count, sum(packetBytes), vector(packetBytes) none

Unassigned submodule parameters

Name Type Default value Description
pcapRecorder.displayStringTextFormat string "rec: %n pks"

Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
pcapRecorder.verbose bool true

Whether to log packets on the module output
pcapRecorder.recordEmptyPackets bool true

Specifies if zero length packets are recorded or not
pcapRecorder.enableConvertingPackets bool true

Specifies if converting packets to link type is allowed or not
pcapRecorder.pcapFile string ""

The PCAP file to be written, suggested value: pcapFile = "${resultdir}/${configname}-#${runnumber}" + fullpath() + ".pcap"
pcapRecorder.fileFormat string "pcapng"
pcapRecorder.snaplen int 65535

Maximum number of bytes to record per packet
pcapRecorder.timePrecision int 6

Time precision in recorded file. pcap supports only 6 (usec) or 9 (nanosec), pcapng supports more values (see 'if_tsresol' option in pcapng file format).
pcapRecorder.dumpBadFrames bool true

Enable dump of frames with hasBitError
pcapRecorder.sendingSignalNames string "transmissionEnded"

Space-separated list of outbound packet signals to subscribe to
pcapRecorder.receivingSignalNames string "receptionEnded"

Space-separated list of inbound packet signals to subscribe to
pcapRecorder.dumpProtocols string "ethernetmac ppp ieee80211mac"

Space-separated list of protocol names as defined in the Protocol class
pcapRecorder.packetFilter object "*"

Which packets are considered, matches all packets by default
pcapRecorder.helpers string ""

Usable PcapRecorder::IHelper helpers for accept packettype and store/convert packet as specified linktype currently available: "inet::AckingMacToEthernetPcapRecorderHelper"
pcapRecorder.alwaysFlush bool false

Flush the pcapFile after each write to ensure that all packets are captured in case of a crash

Source code

//
// A base for external network interfaces, network interface
// modules that connect the simulation to the network stack of the host OS.
//
// Each external interface module is associated with a specific network device
// on the host OS. The host OS device is identified by the "namespace" and
// "device" parameters. The "namespace" parameter is optional; when empty, the
// default namespace is used.
//
// External interfaces can be mentally visualized as composed of an upper and a
// lower part, one of which is the host OS device and the other is part of the
// simulation. Therefore, there are two types of external interfaces, which are
// also reflected in their names:
//
// - In `ExtLower` interfaces, the lower part is a host OS device, and the upper
//   part is in the simulation. Therefore, an `ExtLower` interface module has
//   `upperLayerIn` and `upperLayerOut` gates for connecting to the upper layers.
//   The device is typically a "veth" (virtual Ethernet) device. (Using real
//   interfaces like "eth0" is also possible, but it needs special care to
//   prevent incoming packets from being replied to by both the simulation and the
//   kernel or other processes on the host OS.)
//
// - In `ExtUpper` interfaces, the upper part is a host OS device, and the
//   lower part is the simulated one. Therefore, an `ExtUpper` interface
//   module typically has gates for connecting to the simulated network.
//   The device is typically a "tap" (virtual TUN/TAP) device, which allows
//   the interception of the traffic of the host OS and routing them into the simulation.
//
// `ExtLower` interfaces are in general useful for connecting simulated apps to
// a real network, while `ExtUpper` interfaces are suitable for running a real
// networked application over a simulated network.
//
//
module ExtInterface extends NetworkInterface like IExternalInterface
{
    parameters:
        bool isWireless = default(false);
        string interfaceTableModule; // Module path of the interface table module
        string device; // Name of the attached OS device (e.g. tap0, veth0, etc.)
        string namespace = default("");  // Name of the OS network namespace (optional)
        string copyConfiguration @enum("","copyToExt","copyFromExt") = default(""); // Copy interface configuration such as MAC address, IP address, and MTU from/to the external interface.
        string address @mutable = default("auto");
        bool broadcast = default(true);
        bool multicast = default(true);
        bool pointToPoint = default(false);
        int mtu @unit(B) = default(4470B);
        *.interfaceTableModule = default(absPath(this.interfaceTableModule));
        *.device = default(this.device);
        *.namespace = default(this.namespace);
        @class(ExtInterface);
    gates:
        input upperLayerIn @loose;
        output upperLayerOut @loose;
}
File: src/inet/emulation/common/ExtInterface.ned

This documentation is released under the Creative Commons license