Several usage examples to give you an idea of what you can do with the library.
These examples are gathered as a whole here for quick find, but they are also in each of the module methods.
ip -batch Batch mode support / Man Page
import { batch } from 'iproute';
Executes batch commands from a file
await batch.fromFile({
filePath: '/tmp/filepath'
});
Executes batch commands from stdin
await batch.fromStdin({
stdin: [
'address add local 127.0.1.4/32 dev lo',
'address add local 127.0.1.5/32 dev lo',
'address add local 127.0.1.6/32 dev lo',
'address add local 127.0.1.7/32 dev lo'
].join('\n')
});
ip link Network devices configuration / Man Page
import { link } from 'iproute';
Show link information about the eth0 device
const links = await link.show({
dev: 'eth0'
});
Shortcut to show all links
const links = await link.show();
const links = await link.show({});
The links output is an array of links with the matching LinkInfo[] interface.
Example:
await link.del({
dev: 'eth0.1@eth0'
});
Example:
await link.add({
link: 'lo',
name: 'dummy100',
address: '00:11:22:33:44:55',
mtu: 1500,
type: VirtualLinkTypes.Dummy
});
ip address Protocol address management / Man Page
import { address } from 'iproute';
Show only the eth0 device addresses
const addresses = await address.show({
dev: 'eth0'
});
const addresses = await address.show();
const addresses = await address.show({});
The addresses output is an array of links with the matching LinkWithAddressInfo[] interface.
await address.flush({
dev: 'eth0'
});
await address.add({
local: '10.3.15.3/24',
scope: AddressScopes.Host, // 'host'
dev: 'eth0'
});
await address.del({
local: '10.3.15.3/24'
dev: 'eth0'
});
ip route Routing table management / Man Page
import { route } from 'iproute';
Example:
const routes = await route.show({
table: RouteRoutingTables.All // 'all'
});
The routes output is an array of routes with the matching RouteInfo[] interface.
await route.flush({
table: RouteRoutingTables.Cache // 'cache'
});
Unicast type route (the default if not specified)
await route.add({
to: '10.0.0.0/24',
via: {
address: '192.168.56.1'
}
});
Multipath route with load balance between devices
await route.add({
to: 'default',
scope: AddressScopes.Global, // 'global'
nexthops: [{
nexthop: true,
dev: 'ppp0'
},
{
nexthop: true,
dev: 'ppp1'
}]
});
A NAT route
await route.add({
type: RoutingTableTypes.Nat, // 'nat'
to: '10.0.0.0/24',
table: 300,
via: {
address: '192.168.56.1'
}
});
Delete multipath route with load balance between devices
await route.del({
to: 'default',
scope: AddressScopes.Global, // 'global'
nexthops: [{
nexthop: true,
dev: 'ppp0'
},
{
nexthop: true,
dev: 'ppp1'
}]
});
ip rule Routing policy database (RPDB) management / Man Page
import { rule } from 'iproute';
Unicast type rule (the default if not specified)
await rule.add({
from: '192.203.80.0/24',
table: 300,
preference: 220
});
NAT type rule
await rule.add({
from: '193.233.7.83',
table: 1,
preference: 320,
nat: '192.203.80.144'
});
Delete the unused default rule
await rule.del({
preference: 32767
});
Example:
await rule.flush();
Example:
const rules = await rule.show();
The rules output is an array of routes with the matching RuleInfo[] interface.
ip monitor State monitoring / Man Page
import { monitor } from 'iproute';
Monitor all objects state changes
monitor({
object: MonitorObjects.All // 'all'
});
After starting the monitor, you can start watching for changes
let command: MonitorCommand<MonitorOptions>;
monitor({
object: MonitorObjects.All
})
.then((_command) => {
command = _command;
command.on(MonitorObjects.All, (data: MonitorEmittedData) => {
// Do something with `data`.
});
command.on('error', (error) => {
// Do something with `data`.
});
});
setTimeout(() => {
command.close();
}, 5000);
The data object will hold the iproute output data, which at this moment doesn't support the -json option, so right
now will conform to the interface MonitorEmittedData.
ip addrlabel Protocol address label management / Man Page
import { addrlabel } from 'iproute';
Add an address label
await addrlabel.add({
prefix: '2001:db8::/32',
label: 100,
});
Delete an address label
await addrlabel.del({
prefix: '2001:db8::/32'
});
Example:
await addrlabel.flush();
Example:
const labels = await addrlabel.list();
The labels output is an array of address labels with the matching AddrlabelInfo[] interface.
ip neighbour Neighbour/ARP tables management / Man Page
import { neighbour } from 'iproute';
Add a simple ARP entry
await neighbour.add({
to : '192.168.1.100',
lladdr: '00:aa:bb:cc:dd:ee',
dev : 'eth0'
});
Delete an ARP entry
await neighbour.del({
to : '192.168.1.100',
dev: 'eth0'
});
Example:
await neighbour.flush({
dev: 'eth0'
});
Example:
const entries = await neighbour.show({});
The entries output is an array of ARP entries with the matching NeighbourInfo[] interface.
ip ntable Neighbour table configuration / Man Page
import { ntable } from 'iproute';
Example:
const entries = await ntable.show({});
The entries output is an array of entries with the matching NtableInfo[] interface.
ip tunnel Tunnel configuration / Man Page
import { tunnel } from 'iproute';
Create a new tunnel
await tunnel.add({
name : 'tun0',
mode : TunnelModes.Gre,
remote: '203.0.113.4',
local : '203.0.113.5',
dev : 'eth0'
});
Delete a tunnel
await tunnel.del({
name: 'tun0'
});
Modify an existing tunnel
await tunnel.change({
name : 'tun0',
mode : TunnelModes.Ipip,
remote: '203.0.113.6',
local : '203.0.113.7',
dev : 'eth1'
});
Example:
const entries = await tunnel.show({});
The entries output is an array of tunnel configurations with the matching TunnelInfo[] interface.
Example:
await tunnel.6rd({
dev : 'eth0',
6rd_prefix : '2001:db8::'
});
import { tuntap } from 'iproute';
Create a new tuntap device
await tuntap.add({
mode: TunTapTunnelModes.Tun
});
Delete a tunnel
await tuntap.del({
mode: TunTapTunnelModes.Tun
});
Example:
const entries = await tuntap.show({});
The entries output is an array of tunnel configurations with the matching TunTapTunnelInfo[] interface.
ip maddress Multicast addresses management / Man Page
import { maddress } from 'iproute';
Add a multicast address
await maddress.add({
address: '33:33:00:00:00:01',
dev: 'enp0s3'
});
Delete a tunnel
await maddress.del({
address: '33:33:00:00:00:01',
dev: 'enp0s3'
});
Example:
const entries = await maddress.show({});
The entries output is an array of tunnel configurations with the matching MaddressInfo[] interface.
ip mroute Multicast routing cache management / Man Page
import { mroute } from 'iproute';
Example:
const entries = await mroute.show({});
The entries output is an array of multicast routing entries configurations with the matching MrouteInfo[] interface.
General helpful utils to provide extra handy functionality not present in iproute, like routing table manipulation
and IP forwarding configuration.
See its complete API documentation.
import { utils } from 'iproute';
Allows you to enable/disable IP forwarding, and query for its status.
Specific IPv4 or IPv6 methods:
await utils.ipForwarding.v{4|6}.enable()
await utils.ipForwarding.v{4|6}.disable()
const status = await utils.ipForwarding.v{4|6}.status()
General methods affecting both IPv4 and IPv6:
await utils.ipForwarding.enable()
await utils.ipForwarding.disable()
const status = await utils.ipForwarding.status()
Provides routing tables manipulation functions, like table creation, deletion and querying.
Those are wrapper functions to manage the /etc/iproute/rt_tables file.
Note: You have to flush the routing cache after making modifications in the routing tables:
import { route } from 'iproute'; await route.flush({ table: RouteRoutingTables.Cache // 'cache' });
Show all tables
const tables = await utils.routingTables.show();
Show table with id 255
const tables = await utils.routingTables.show({
id: 255
});
Show table with name local
const tables = await show({
name: RoutingTables.Local // 'local'
});
The tables output is an array of tables with the expected following structure
[
{ id: '254', name: 'main' },
{ id: '0', name: 'unspec' },
{ id: '253', name: 'default' },
{ id: '255', name: 'local' }
]
It adheres to the RoutingTable interface.
It will add passed in table if it is not already present.
Add a single table
await utils.routingTables.add({
id: 50,
name: 'table_name'
});
Add more than one table
await utils.routingTables.add([{
id: 50,
name: 'table_name'
}, {
id: 51,
name: 'table_name2'
}]);
It will remove the specified table if it exists.
await utils.routingTables.delete({
id: 50
});
Delete more than one table.
await utils.routingTables.delete([{
id: 51
}, {
id: 52
}]);
Note: It will clear/remove all the present tables so use it carefully!
It doesn't immediately flush the route cache, allowing you to continue making changes (like adding new tables) before the modifications take effect and routes with unreferenced tables are discarded.
Clear all tables
await utils.routingTables.clear();
Flush route cache so the changes become active
import { route } from 'iproute';
await utils.routingTables.clear();
await route.flush({
table: RouteRoutingTables.Cache // 'cache'
});