# 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.

User can use the following code to import the advnwc module.

var advnwc = require('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

# advnwc.netifs(lan, callback)

• lan {Boolean} LAN (true) or WAN (false) network interface.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • list {Array} | {Object} Network interface name array.

Get the current machine's LAN or WAN network interface list, if the current machine is not a router, when getting the WAN list, the callback function will get an error.

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: (This feature is available in EdgerOS 1.6.0 and later)

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

# Example

advnwc.netifs(true, function(error, list) {
  if (error) {
    console.error(error.message);
  } else {
    console.log('LAN port interface:', list);
  }
});

# advnwc.hosts(callback)

• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • list {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', function() {
  advnwc.hosts(function(error, hosts) {
    if (Array.isArray(hosts)) {
      // ...
    }
  });
});

The following functions needs permission.advnwc permission to use. For details, please refer to permission.

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

• 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.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • index {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, function(error, index) {
  if (error) {
    console.error(error.message);
  } else {
    console.log('New rule index:', index);
  }
});

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

• ifname {String} Which network interface.
• index {Integer} Rule index.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.

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

advnwc.qosAdd(..., function(error, index) {
  if (typeof index === 'number') {
    advnwc.qosDelete(undefined, index);
  }
});

# advnwc.qosList(ifname, index, callback)

• ifname {String} Which network interface.
• index {Integer} Rule index.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • rules {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('en1', undefined, function(error, rules) {
  if (Array.isArray(rules)) {
    rules.forEach(function(rule) {
      console.log(rule);
    });
  }
});

# advnwc.npfAdd(rule, ifname, allow, mac, ipStart, ipEnd, portStart, portEnd[, ipStartPairs, ipEndPairs, portStartSrc, portEndSrc], callback[, 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.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • index {Integer} New QoS rule index.
• opt {Object} Options.
  • nforward {Boolean} Only denied routing forwarding when blocking. default: false denied all.

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', undefined, undefined, undefined, undefined, function(error, index) {
  // ...
});

// 'ipStart' address must be less than 'ipEnd'
advnwc.npfAdd('ip', 'en1', false, '10.0.0.3', '10.0.0.50', undefined, undefined, function(error, index) {
  if (error) {
    console.error(error.message);
  } else {
    console.log('New rule index:', index);
  }
});

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

• ifname {String} Which network interface.
• index {Integer} Rule index.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.

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

advnwc.npfAdd(..., function(error, index) {
  if (typeof index === 'number') {
    advnwc.npfDelete(undefined, index);
  }
});

# advnwc.npfList(ifname, index, callback)

• ifname {String} Which network interface.
• index {Integer} Rule index.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • rules {Array | Object} List of all net packet filter 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('en1', undefined, function(error, rules) {
  if (Array.isArray(rules)) {
    rules.forEach(function(rule) {
      console.log(rule);
    });
  }
});

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

• 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.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • index {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, function(error, index){
  // ...
});

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

• ifname {String} Which network interface.
• index {Integer} Rule index.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.

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

advnwc.flowAdd(..., function(error, index) {
  if (typeof index === 'number') {
    advnwc.flowDelete(undefined, index);
  }
});

# advnwc.flowList(ifname, index, callback)

• ifname {String} Which network interface.
• index {Integer} Rule index.
• callback {Function} Callback function.
  • error {Error} Indicate an error information when an error occurs.
  • rules {Array | Object} List of all flow control rule 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('en1', undefined, function(error, rules) {
  if (Array.isArray(rules)) {
    rules.forEach(function(rule) {
      console.log(rule);
    });
  }
});