# AdvNwc : Advance network control

This module is an EdgerOS advanced network control service module and an application with corresponding permissions can use this module to control network Traffic, QoS, Network Shielding, etc. This module is available in EdgerOS 1.6.0 and later.

This module is the asynchronous mode of the advnwc module. User can use the following code to import the advnwc module.

var advnwc = require('async/advnwc');

The application can list all currently existing rules, but can only delete rules added by itself. When the application exits, all rules added by itself will be automatically cleared.

# Support

The following shows advnwc module APIs available for each permissions.

# AdvNwc Object

# async advnwc.netifs(lan)

• lan {Boolean} LAN (true) or WAN (false) network interface.
• Returns: {Array} Network interface name array.

Get the current machine's LAN or WAN network interface list, if the current machine is not a router, an exception will be thrown when getting the WAN list.

If the argument lan is not of {Boolean} type, get list of LAN and WAN network interfaces at the same time, and return it as an object, including the following members:

• lans {Array} Network interface name array of LAN.
• wans {Array} Network interface name array of WAN.

# Example

advnwc.netifs(true).then(list => {
  for (var ifname of list) {
    console.log(ifname);
  }
}).catch(console.error);

# advnwc.hosts()

• Returns: {Array} Current LAN network connection host information list.

Get the current LAN network connection host information list. Each host object in the list contains the following members:

• name {String} Host name.
• addr {String} Host IP address.
• type {String} Host type, include: 'Phone', 'Pad', 'PC', 'Printer', 'TV', 'Camera', 'Device', 'Unknown'.
• model {String} Host sub model info. May be empty string.
• mac {String} Host MAC address. may not exist. Optional.
• vendor {String} Host vendor. may not exist. Optional.

The host connection change event can be obtained by listening to the 'host' event of advnwc.

# Example

advnwc.on('host', () => {
  advnwc.hosts().then(hosts => {
    // ...
  }).catch(console.error);
});

# async advnwc.qosAdd(rule, ifname, policy, prio, ipStart, ipEnd[, portStart[, portEnd[, reliable]]])

• rule {String} Rule name: 'IP', 'TCP' or 'UDP'.
• ifname {String} Which network interface.
• policy {String} Policy of this rule.
• prio {Integer} Priority of packets that meet this rule.
• ipStart {String} Starting IP address.
• ipEnd {String} End IP address.
• portStart {Integer} Starting TCP or UDP port.
• portEnd {Integer} End TCP or UDP port.
• reliable {Boolean} Whether to enable reliable reception guarantee. default: false.
• Returns: {Integer} New QoS rule index.

policy can choose 's' for source address range, 'd' for destination address range, and 'sd' for both address range.

prio indicates the priority of data packets, and the value range is 0 (lowest) ~ 7 (highest).

Add a QoS rule, and the EdgerOS network protocol stack will process the queued data packets in different priorities according to the rule settings, ensuring that the network data that needs to be processed in real time is faster and more reliable.

# Example

// 'ipStart' address must be less than 'ipEnd'
advnwc.qosAdd('tcp', 'en1', 'd', 5, '10.0.0.3', '10.0.0.50', 80, 80, false).then(index => {
  console.log('New rule index:', index);
}).catch(console.error);

# async advnwc.qosDelete(ifname[, index])

• ifname {String} Which network interface.
• index {Integer} Rule index.
• Returns: {Boolean} Whether the operation was successful.

Delete a previously added QoS rule. If index is of type {Integer}, delete the rule of specified index. If index is not of type {Integer}, delete all rules of the network interface specified by ifname.

# Example

async function test() {
  var index = await advnwc.qosAdd(...);
  return advnwc.qosDelete(undefined, index);
}

# async advnwc.qosList([ifname[, index]])

• ifname {String} Which network interface.
• index {Integer} Rule index.
• Returns: {Array | Object} List of all QoS rules added previously.

Each rule object in rules array, which contains the following properties:

• ifname {String} Network interface name.
• index {Integer} Index number of this rule.
• rule {String} Type of this rule: 'IP', 'TCP' or 'UDP'.
• policy {String} Policy of this rule.
• ipStart {String} Starting IP address.
• ipEnd {String} End IP address.
• portStart {Integer} Starting TCP or UDP port.
• portEnd {Integer} End TCP or UDP port.
• prio {Integer} Priority.
• reliable {Boolean} Whether to enable reliable reception guarantee.

Get the list of specified QoS rules, If ifname and index are both undefined, get all QoS rule entries. If you specify an index, return a single rule object.

# Example

advnwc.qosList().then(list => {
  for (var rule of list) {
    console.log(JSON.stringify(rule));
  }
}).catch(console.error);

# async advnwc.npfAdd(rule, ifname, allow, mac, ipStart, ipEnd, portStart, portEnd[, ipStartPairs, ipEndPairs, portStartSrc, portEndSrc][, opt])

• rule {String} Rule name: 'MAC', 'IP', 'TCP' or 'UDP'.
• ifname {String} Which network interface.
• allow {Boolean} Whether to allow this packet.
• mac {String} Ethernet MAC address.
• ipStart {String} Starting IP address.
• ipEnd {String} End IP address.
• portStart {Integer} Starting TCP or UDP destination port.
• portEnd {Integer} End TCP or UDP destination port.
• ipStartPairs {String} Starting IP address pairs.
• ipEndPairs {String} End IP address, pairs.
• portStartSrc {Integer} Starting TCP or UDP source port.
• portEndSrc {Integer} End TCP or UDP source port.
• opt {Object} Options.
  • nforward {Boolean} Only denied routing forwarding when blocking. default: false denied all.
• Returns: {Integer} New NPF rule index.

Only need to set mac when rule is 'MAC', otherwise mac can be undefined.

Add a net packet filter, this method can isolate some specified devices in the network. When allow is true, it means to join the whitelist, otherwise it will be added to the blacklist. The whitelist priority is higher then blacklist.

If ipStartPairs is specified, ipEndPairs, portStartSrc, portEndSrc must be specified, this feature indicates that this filtering rule agrees on the address range of both communication parties, this feature is valid in EdgerOS 2.1.4 and above.

# Example

advnwc.npfAdd('mac', 'en1', false, '00:11:22:33:44:55').then(index => {
  // ...
}).catch(console.error);

// 'ipStart' address must be less than 'ipEnd'
advnwc.npfAdd('ip', 'en1', false, '10.0.0.3', '10.0.0.50').then(index => {
  console.log('New rule index:', index);
}).catch(console.error);

# async advnwc.npfDelete(ifname[, index])

• ifname {String} Which network interface.
• index {Integer} Rule index.
• Returns: {Boolean} Whether the operation was successful.

Delete a previously added net packet filter. If index is of type {Integer}, delete the rule of specified index. If index is not of type {Integer}, delete all rules of the network interface specified by ifname.

# Example

async function test() {
  var index = await advnwc.npfAdd(...);
  return advnwc.npfDelete(undefined, index);
}

# async advnwc.npfList([ifname[, index]])

• ifname {String} Which network interface.
• index {Integer} Rule index.
• Returns: {Array | Object} List of all NPF rules added previously.

Each rule object in rules array, which contains the following properties:

• ifname {String} Network interface name.
• index {Integer} Index number of this rule.
• rule {String} Type of this rule: 'MAC', 'IP', 'TCP' or 'UDP'.
• allow {Boolean} Whether to allow this packet.
• nforward {Boolean} Only denied routing forwarding when blocking.
• mac {String} If it is a MAC filtering rule, this attribute holds the MAC address. (Only in 'MAC' rule)
• ipStart {String} Starting IP address. (Only in 'IP', 'TCP' or 'UDP' rules)
• ipEnd {String} End IP address. (Only in 'IP', 'TCP' or 'UDP' rules)
• portStart {Integer} Starting TCP or UDP destination port. (Only in 'TCP' or 'UDP' rules)
• portEnd {Integer} End TCP or UDP destination port. (Only in 'TCP' or 'UDP' rules)
• ipStartPairs {String} Starting IP address pairs. (Only with pairs arguments rules)
• ipEndPairs {String} End IP address, pairs. (Only with pairs arguments rules)
• portStartSrc {Integer} Starting TCP or UDP source port. (Only with pairs arguments rules)
• portEndSrc {Integer} End TCP or UDP source port. (Only with pairs arguments rules)

Get the list of specified NPF rules, If ifname and index are both undefined, get all NPF rule entries. If you specify an index, return a single rule object.

# Example

advnwc.npfList().then(list => {
  for (var rule of list) {
    console.log(JSON.stringify(rule));
  }
}).catch(console.error);

# async advnwc.flowAdd(rule, ifname, upLimit, downLimit[, ipStart[, ipEnd[, portStart[, portEnd[, bufSize]]]]])

• rule {String} Rule name: 'IP', 'TCP' or 'UDP'.
• ifname {String} Which network interface.
• upLimit {Integer} Uplink speed limit (>= 10000Bps).
• downLimit {Integer} Downlink speed limit (>= 10000Bps).
• ipStart {String} Starting IP address.
• ipEnd {String} End IP address.
• portStart {Integer} Starting TCP or UDP port.
• portEnd {Integer} End TCP or UDP port.
• bufSize {Integer} Buffer size bytes (32KB ~ 256KB). default: 64KB.
• Returns: {Integer} New flow control rule index.

Add a flow control rule to control the uplink and downlink speeds of the internal network machines. When the speed exceeds the speed limit, these packets will be buffered. The bufSize parameter determines the buffer size of the buffer.

# Example

// Uplink 512 KBps, downlink 1 MBps
advnwc.flowAdd('tcp', 'en1', 512 * 1000, 1000 * 1000, '10.0.0.3', '10.0.0.50', 80, 80, 64 * 1024).then(index => {
  // ...
}).catch(console.error);

# async advnwc.flowDelete(ifname[, index])

• ifname {String} Which network interface.
• index {Integer} Rule index.
• Returns: {Boolean} Whether the operation was successful.

Delete a previously added flow control rule. If index is of type {Integer}, delete the rule of specified index. If index is not of type {Integer}, delete all rules of the network interface specified by ifname.

# Example

async function test() {
  var index = await advnwc.flowDelete(...);
  return advnwc.flowDelete(undefined, index);
}

# async advnwc.flowList([ifname[, index]])

• ifname {String} Which network interface.
• index {Integer} Rule index.
• Returns: {Array | Object} List of all flow control rules added previously.

Each rule object in rules array, which contains the following properties:

• ifname {String} Network interface name.
• index {Integer} Index number of this rule.
• rule {String} Type of this rule: 'IP', 'TCP' or 'UDP'.
• upLimit {Integer} Uplink speed limit.
• downLimit {Integer} Downlink speed limit.
• ipStart {String} Starting IP address.
• ipEnd {String} End IP address.
• portStart {Integer} Starting TCP or UDP port.
• portEnd {Integer} End TCP or UDP port.
• bufSize {Integer} Buffer size bytes.

Get the list of specified flow control rules, If ifname and index are both undefined, get all flow control rule entries. If you specify an index, return a single rule object.

# Example

advnwc.flowList().then(list => {
  for (var rule of list) {
    console.log(JSON.stringify(rule));
  }
}).catch(console.error);