Documentation (v2.0.0)
This is the documentation for the $ net-runner-engine$ , Node.js wrapper for the $ NS3$ library and the module used to simulate networks constructed in the $ playground$ .
Table of contents
Installation
To install this package simply run:
npm install net-runner-engine --saveThe installation might be slow, because prebuilt NS3 binaries would be downloading (around 100MB).
Primitives
Time string
This data type represents a common time expressions like "1ms". Is is basically a string of format {numberOfUnits}{unitOfTime}. There can be no white space between numerical part and unit. Available time units: s (seconds), ms (milliseconds), us (microseconds), ns (nanoseconds), ps (picoseconds), fs (femtoseconds), min (minutes), h (hours), d (days), y (years).
Rate string
This data type represents a data rate value. Like TimeString, it is a string of format {numberOfUnits}{unit}. Available units: bps, b/s, Bps, B/s, kbps, kb/s, Kbps, Kb/s, kBps, kB/s, KBps, KB/s, Kib/s, KiB/s, Mbps, Mb/s, MBps, MB/s, Mib/s, MiB/s, Gbps, Gb/s, GBps, GB/s, Gib/s, GiB/s.
IP string
String which holds an IP address. Currently only IPv4 is supported.
Network
The Network holds the network data, i.e. nodes and connection between them. The typical use case for this class is to add some nodes to it, connect these nodes and run the network via it's method run .
Network options
Name | type | default value | description |
animeLen | Number | 3 | Lifetime of network in seconds |
populateIP | Boolean | false | Initialize the routing database and set up static unicast forwarding tables for each node.
Turns every node in the network into router. |
Run options
name | type | default value | description |
upload | Boolean | false | Whether to upload simulation results to the website |
Methods
Method name | arguments | DEFAULT | DESCRIPTION |
Constructor | options: NetworkOptions | { } | Class constructor |
setOptions | options: NetworkOptions | { } | Modify instance options |
addNode | node: Node | | Add node to the network |
removeNode | node: Node | | Remove node from the network |
run | outputPath: String, options: RunOptions | | Simulate the network and collect associated files,
i.e. PCAP dumps in the outputPath. If upload option is set
to true, then this methods uploads resulting files to the website
and return Recording URL. |
Node
Base class for all modules.
Node constructor options
NAME | TYPE | DEFAULT VALUE | DESCRIPTION |
name | String | Generated automatically, e.g. Node2 | Name of the node used to generate names for PCAP files |
x | Number | Generated automatically | X-coordinate of the node |
y | Number | Generated automatically | Y-coordinate of the node |
Connect options
NAME | TYPE | DEFAULT VALUE | DESCRIPTION |
sourceIP | IPString | required if source is Host | Source node IP address |
targetIP | IPString | required is target is Host | Target node IP address |
dataRate | RateString | 5Mbps | Data rate of the connection |
delay | TimeString | 5ms | Transmission delay through the channel |
sourceMask | IpString | 255.255.255.0 | IPv4 mask for source IP address |
targetMask | IpString | 255.255.255.0 | Ipv4 mask for target IP address |
Node methods
METHOD name | arguments | default | description |
Constructor | options: NodeConstructorOptions | { } | Class constructor |
connect | node: Node, options: ConnectOptions | | Connect one to another, both nodes must belong
to the same network |
disconnect | node: Node | | Disconnect two nodes |
new Node(net, options), that calls net.addNode(node) in the constructor body.
Node children classes
Host
This node represents the end client in the network, e.g. web-server, hence it can have applications. Additional methods:
METHOD NAME | ARGUMENTS | DEFAULT | DESCRIPTION |
setupApllication | app: Application | required | Add application to node |
removeApplication | app: Application | required | Remove application from node |
Hub
This node represents the CSMA hub. Additional constructor options:
NAME | TYPE | DEFAULT VALUE | description |
delay | TimeString | 5ms | Transmission delay through the CSMA channel |
dataRate | RateString | 5Mbps | Data rate of the connections to hub |
ConnectionOptions. Use hub constructor options to define them.
Switch
This node represents the $ NS3 Openflow Switch$ .
Application
As mentioned above, applications can be installed on Host nodes via setupApplication method. Every application is a class inherited from base class Application, and all of them expose only a constructor. Below there is a list of constructor options for all available applications:
Ping
This application send ICMP packets to specified destination. Constructor options:
NAME | type | default | description |
interval | TimeString | 0.5s | Time interval to ping |
addr | IpString | required | IP address to ping |
Sink
This application just consumes packets on specified address. Constructor options:
NAME | TYPE | default | description |
addr | IpString | 0.0.0.0 | Address to bind socket |
UDP server
Listens for UDP requests. Constructor options:
NAME | type | default | description |
addr | IpString | 0.0.0.0 | Address to bind socket to |
port | Number | required | Port to bind socket to |
onReceive | onReceiveCallback | | See onReceive/onTick section |
TCP server
Communicates with TCP client. Constructor options:
NAME | type | default | description |
addr | IpString | 0.0.0.0 | Address to bind socket to |
port | Number | required | See onReceive/onTick section |
onReceive | onReceiveCallback | | See onReceive/onTick section |
UDP Client
Sends UDP packets to the specified destination. Constructor options:
NAME | type | default | description |
addr | IpString | required | Address to send packets to |
port | Number | required | Port to send packets to |
dataRate | RateString | 5Mbps | Data rate to generate with application |
maxBytes | Number | 0 | Limit of bytes to send. Unlimited if the option is set to 0 |
onTick | onTickCallback | | See onReceive/onTick section |
tickInterval | TimeString | See onReceive/onTick section | |
packetSize | Number | 256 | Packet size in bytes |
TCP Client
Communicates with TCP server. Constructor options:
name | type | default | description |
addr | IpString | required | Address to stream packets to |
port | Number | required | Port to stream packets to |
dataRate | RateString | 5Mbps | Data rate to generate with application |
maxBytes | Number | 0 | Limit of bytes to send. Unlimited if the option is set to 0 |
onTick | onTickCallback | | See onReceive/onTick section |
tickInterval | TimeString | | See onReceive/onTick section |
packetSize | Number | 256 | Packet size in bytes |
Raw socket client
This application aims to simulate Linux raw sockets and is intended to be used with onTick/onReceive functionality. Constructor options:
name | type | default | description |
addr | IpString | required | Address to send packets to |
onTick | onTickCallback | | See onReceive/onTick |
tickInterval | TimeString | | See onReceive/onTick |
Raw socket server
This application aims to simulate Linux raw sockets and is intended to be used with onTick/onReceive functionality. Constructor options:
name | type | default | description |
addr | IpString | 0.0.0.0 | Address to bind socket to |
onReceive | onReceiveCallback | | see onReceive/onTick |
onReceive/onTick
This two options accept a callback function, which lets user to interact with simulation events from Node.js. These functions accept object with specific fields, that provide the bridge between Node.js and NS3.
onTick
The argument for this function is an object with the following properties:
time— time inside simulation event scheduler.sendPacket— function which takes single argument of typeBuffer, the packet to send.
If onTick callback returns TimeString, then the next schedule time will be equal to current time + returned time, otherwise if the tickInterval option was specified, the tickInterval value would be used like it was returned by function. Example of using onTick:
onTick: ({ time, sendPacket }) => { if (time > 1000) { const buf = Buffer.from('hello'); sendPacket(buf); //accepts Buffer only } return '1s'; //call onTick after 0.1s }
onReceive
The argument for this function is an object with the following properties:
address— the address of sender.packet— received packet.reply— function which takes single argument of typeBuffer, the packet to send.
There is no additional scheduling logic when using this function. Example of using onReceive:
onReceive: ({ address, packet, reply }) => {
console.log('[*] receive', address, packet);
const buf = Buffer.from('world');
reply(buf);
}
Known bugs & issues
At the time writing this post there are some known issues using this module:
- The module can be installed only on Linux x64.
onTick/onReceivecallbacks can't be asynchronous since NS3 is a discrete-event network simulator. It provides functionality to schedule events inside it's internal event loop, for which one provide a callback, which has to be synchronous.