Documentation (v2.0.0)

Net-runner
Documentation (v2.0.0)

1 year ago by Seva D. (sabrinarempel7@gmail.com)
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
Primitives
Time string
Rate string
IP string
Network
Network options
Run options
Methods
Node
Node constructor options
Connect options
Node methods
Node children classes
Host
Hub
Switch
Application
Ping
Sink
UDP server
TCP server
UDP Client
TCP Client
Raw socket client
Raw socket server
onReceive/onTick
onTick
onReceive
Known bugs & issues
﻿
Installation
To install this package simply run:
npm install net-runner-engine --save
The 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
note:Since version 2.0.4 you can use the convenience overload of the constructor: 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
﻿
note:Connections in hub network ignore the delay and dataRate in the 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 type Buffer, 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 type Buffer, 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/onReceive callbacks 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.
﻿
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.
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.