Show and manipulate network devices, routing, policy routing and tunnels.
Wrapper around native iproute suite to port its functionality to be used in Node.js space.
$ npm install iproute
ip-linkNetwork devices configuration.ip-addressProtocol address management.ip-routeRouting table management.ip-ruleRouting policy database (RPDB) management.ip-monitorState monitoring.ip-utilsCustom utility library that complementsiproutesuite.
As the current Node.js version all the network related functionality that the built-in modules provide is quite limited,
and mostly only gives read-only information through os.networkInterfaces() method, despite the fact that Unix/Linux
networking related functions are awesome.
This module appeal that issue in the Unix/Linux platform by providing methods wrapping the iproute user-space suite.
With this module you will be able to interact with the iproute commands without have to care about executing directly any command or so, and will give you several handy utilities that will parse shown information for you.
By using it you will save a lot of boilerplate code that the module do for you and are shared among all commands.
Basically the only system requirement is that the iproute utility have to be present in your system.
You can install it in Debian based OSes (if is not already there) by issuing:
sudo apt-get install iproute
Other requirement is about permission levels. To properly execute the provided write methods like .add(), .set(),
.delete()) the application that uses the module must have the proper sudo privileges.
The source is available for download from GitHub and there is a issue tracker so you can report bugs there.
As a general rule of thumb, all the module identifiers are the same that iproute provides, so you can easily use
the module with basic iproute knowledge.
var ip_utils = require('iproute').utils;
Since this module is to provide extra functionality, is described in another readme file to make this one compact. Check README-utils.md in the project root directory for information about it.
var ip_link = require('iproute').link;
iproute official manual: http://stuff.onse.fi/man?program=ip-link
Examples:
Show link information about the eth0 device
ip_link.show({
dev: 'eth0'
}, function (error, links) {
if (error) {
console.log(error);
}
else {
console.log(links);
}
});
Shortcut to show all links
ip_link.show(function (error, links) {
if (error) {
console.log(error);
}
else {
console.log(links);
}
});
The same as can be accomplished by passing an empty object as the first parameter
ip_link.show({}, function (error, links) {
if (error) {
console.log(error);
}
else {
console.log(links);
}
});
The links output is an array of links with the expected following structure
[{
index: 1,
name: 'eth0',
flags: [
'NO-CARRIER',
'BROADCAST',
'MULTICAST',
'UP'
],
type: 'ether',
mac: '00:24:d6:1c:2f:a6',
brd: 'ff:ff:ff:ff:ff:ff',
mtu: 1500,
qdisc: 'pfifo_fast',
state: 'DOWN',
mode: 'DEFAULT',
qlen: 1000
}]
This is a links example in case of a VLAN virtual link
[{
index: 2,
name: 'eth0.1',
flags: [
'NO-CARRIER',
'BROADCAST',
'MULTICAST',
'UP'
],
type: 'ether',
vl_type: 'vlan',
mac: '00:24:d6:1c:2f:a6',
brd: 'ff:ff:ff:ff:ff:ff',
mtu: 1500,
qdisc: 'noqueue',
state: 'LOWERLAYERDOWN',
mode: 'DEFAULT'
}]
Example:
ip_link.delete({
dev: 'eth0.1@eth0'
}, function (error) {
if (error) {
console.log(error);
}
});
Example:
ip_link.add({
link: 'eth0',
name: 'eth0.1',
type: 'vlan',
type_args: [{
id: 1
}],
}, function (error) {
if (error) {
console.log(error);
}
});
Example:
ip_link.set({
dev: 'eth0',
state: 'down'
}, function (error) {
if (error) {
console.log(error);
}
});
var ip_address = require('iproute').address;
iproute official manual: http://stuff.onse.fi/man?program=ip-address
Examples:
Show only the eth0 device addresses
ip_address.show({
dev: 'eth0'
}, function (error, addresses) {
if (error) {
console.log(error);
}
else {
console.log(addresses);
}
});
Shortcut to show all links with its addresses
ip_address.show(function (error, addresses) {
if (error) {
console.log(error);
}
else {
console.log(addresses);
}
});
The same as can be accomplished by passing an empty object as the first parameter
ip_address.show({}, function (error, addresses) {
if (error) {
console.log(error);
}
else {
console.log(addresses);
}
});
The addresses output is a collection of links with the expected following structure
{
eth0: [{
type: 'ether',
mac: '00:24:be:42:3c:f5',
brd : 'ff:ff:ff:ff:ff:ff'
}, {
type: 'inet',
address:'10.10.10.10/8',
scope: 'host'
}]
}
Examples:
ip_address.flush({
dev: 'eth0'
}, function (error) {
if (error) {
console.log(error);
}
});
Examples:
ip_address.add({
dev: 'eth0',
scope: 'host',
local: '10.3.15.3/24'
}, function (error) {
if (error) {
console.log(error);
}
});
Examples:
ip_address.delete({
address: '10.3.15.3/24'
dev: 'eth0'
}, function (error) {
if (error) {
console.log(error);
}
});
var ip_route = require('iproute').route;
iproute official manual: http://stuff.onse.fi/man?program=ip-route
Example:
ip_route.show({
table:'all'
},function (error, routes) {
if (error) {
console.log(error);
}
else {
console.log(routes);
}
});
The routes output is an array of routes with the expected following structure
[{
type: 'unicast',
to: '127.0.0.0/24',
via: '127.0.0.1',
dev: 'lo'
},
{
type: 'broadcast',
to: '127.0.0.0',
dev: 'lo',
table: 'local',
proto: 'kernel',
scope: 'link',
src: '127.0.0.1'
},
{
type: 'local',
to: '127.0.0.0/8',
dev: 'lo',
table: 'local',
proto: 'kernel',
scope: 'host',
src: '127.0.0.1'
}]
Examples:
ip_route.flush({
table: 'cache'
}, function (error) {
if (error) {
console.log(error);
}
});
Examples:
Unicast type route (the default if not specified)
ip_route.add({
to: '10.0.0.0/24',
via: '192.168.56.1'
}, function (error) {
if (error) {
console.log(error);
}
});
Multipath route with load balance between devices
ip_route.add({
to: 'default',
scope: 'global',
nexthop: [{
dev: 'ppp0'
},
{
dev: 'ppp1'
}]
}, function (error) {
if (error) {
console.log(error);
}
});
A NAT route
ip_route.add({
to: '10.0.0.0/24',
type: 'nat',
via: '192.168.56.1',
table: 'natted_routes'
}, function (error) {
if (error) {
console.log(error);
}
});
Examples:
Delete multipath route with load balance between devices
ip_route.delete({
to: 'default',
scope: 'global',
nexthop: [{
dev: 'ppp0'
},
{
dev: 'ppp1'
}]
}, function (error) {
if (error) {
console.log(error);
}
});
var ip_rule = require('iproute').rule;
iproute official manual: http://stuff.onse.fi/man?program=ip-rule§ion=8
Examples:
Unicast type rule (the default if not specified)
ip_rule.add({
from: '192.203.80.0/24',
table: 'inr.ruhep',
priority: '220'
}, function (error) {
if (error) {
console.log(error);
}
});
NAT type rule
ip_rule.add({
from: '193.233.7.83',
nat: '192.203.80.144',
table: '1',
priority: '320'
}, function (error) {
if (error) {
console.log(error);
}
});
Examples:
Delete the unused default rule
ip_rule.delete({
priority: '32767'
}, function (error) {
if (error) {
console.log(error);
}
});
Example:
ip_rule.flush(function (error) {
if (error) {
console.log(error);
}
});
Example:
ip_rule.show(function (error, rules) {
if (error) {
console.log(error);
}
else {
console.log(rules);
}
});
The rules output is an array of rules with the expected following structure
[
{
priority: '0',
type : 'unicast',
from : 'all',
lookup : 'local'
},
{
priority: '320',
type : 'masquerade',
from : '192.233.7.83',
lookup : 'default'
},
{
priority: '32763',
type : 'prohibit',
from : '192.169.16.0/24',
lookup : 'default'
},
{
priority: '32764',
type : 'unreachable',
from : '192.169.16.0/24',
lookup : 'default'
},
{
priority: '32766',
type : 'unicast',
from : 'all',
lookup : 'main'
},
{
priority: '32767',
type : 'unicast',
from : 'all',
lookup : 'default'
}
]
var ip_monitor = require('iproute').monitor();
iproute official manual: http://stuff.onse.fi/man?program=ip-monitor§ion=8
Examples:
Monitor all objects state changes
ip_monitor();
After starting the monitor, you can start watching for changes:
ip_monitor.on('all',function(data){
console.log(data);
});
ip_monitor.on('link',function(data){
console.log(data);
});
The data object will hold the object type and the already parsed data, as it will be returned by any of the previous
.show() methods. For instance, if the object is a link, the data object could be:
{
object: 'link',
data: [{
index: 1,
name: 'eth0',
flags: [
'NO-CARRIER',
'BROADCAST',
'MULTICAST',
'UP'
],
type: 'ether',
mac: '00:24:d6:1c:2f:a6',
brd: 'ff:ff:ff:ff:ff:ff',
mtu: 1500,
qdisc: 'pfifo_fast',
state: 'DOWN',
mode: 'DEFAULT',
qlen: 1000
}]
}
- Added initial
ip-monitorsupport for links.
-
Added
ip-routesupport. -
Added
ip-utilsutility functions to provide extra functionality that complementsiproute.
- Added
ip-rulesupport.
-
Improved error logging.
-
Improved options handling.
- Added
ip-addresssupport.
- Added
ip-linksupport.
The MIT License (MIT)
Copyright (c) 2013 Diosney Sarmiento
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.