simple-ifconfig

This module aims to provide additional information beyond what the os.networkInterfaces() method returns (via Node) for each detected network interface.

Requirements

• Node.js: >= v6.x
• Platform: Darwin, Unix or Linux (Windows is not supported at this time)

Installation

npm install simple-ifconfig

Usage

Constructor

Creates a new instance of the NetworkInfo class that allows for interaction with the networking interfaces of the system.

new NetworkInfo(options)

Options (optional)

• ifconfigPath (optional, String) - defaults to /sbin/ifconfig when not provided; defines the path to the ifconfig executable
• active (optional, Boolean) - defaults to true when not provided; when true, only the interfaces that are connected and actively transmitting data are included
• internal (optional, Boolean) - defaults to false when not provided; when true, internal (i.e. loopback, etc.) adapters are included when interacting with various other module methods
• verbose (optional, Booelan) - defaults to true when not provided; when true, ifconfig is called with the verbose flag (-v) - on some distros (i.e. Alpine Linux) this flag is not supported and it is helpful to turn it off

import { NetworkInfo } from 'simple-ifconfig';

const
  ifconfigPath = '/sbin/ifconfg',
  active = false,
  internal = false;

let networking = new NetworkInfo({
  ifconfigPath,
  active,
  internal
});

// work with networking instance...

#applySettings

Uses ifconfig to set hardwareAddress, ipv4, mtu as well as up/down (active) status for an interface.

new NetworkInfo().applySettings(interfaceName, settings)

import { NetworkInfo } from 'simple-ifconfig';

let networking = new NetworkInfo();

networking
  .applySettings(`eth0`, {
    active : true,
    hardwareAddress : 'AA:BB:CC:00:11:22',
    ipv4 : {
      address : '192.168.0.2',
      broadcast : '192.168.0.1',
      netmask : '255.255.255.0'
    },
    mtu : 1800
  })
  .then(console.log)
  .catch(console.error);

• active (optional, Boolean) - brings the interface specified up when true or down when false
• hardwareAddress (optional, String) - will change the MAC address of the specified interface to the provided value when specified
• ipv4 (optional, Object) - will allow for specifying IP address (STATIC) configuration for the specified interface
  • address (optional, String)
  • broadcast (optional, String)
  • netmask (optional, String)
• mtu (optional, Number) - when provided, sets the MTU for the specified interface

note: in order to clear a statically configured IP address, most OS variants support providing 0.0.0.0 to "unset" the previously specified address, broadcast and subnet

#listInterfaces

Retrieves an array of available interfaces, optionally filtered according to options provided to the constructor.

new NetworkInfo().listInterfaces()

import { NetworkInfo } from 'simple-ifconfig';

let networking = new NetworkInfo();

networking.listInterfaces()
  .then(console.log)
  .catch(console.error);

Example output:

[ { hardwareAddress: '28:cf:e9:17:99:a9',
    internal: false,
    name: 'en0',
    flags:
     { broadcast: true,
       multicast: true,
       running: true,
       simplex: true,
       smart: true,
       up: true },
    index: 4,
    mtu: 1500,
    ipv6: [ { address: 'fe80::8f0:d3fc:39a2:bb9d', prefixLength: 64 } ],
    ipv4:
     [ { address: '10.129.14.60',
         netmask: '255.255.255.0',
         broadcast: '10.129.14.255' } ],
    active: true },
  { hardwareAddress: 'a8:20:66:16:d4:9d',
    internal: false,
    name: 'en3',
    flags:
     { broadcast: true,
       multicast: true,
       running: true,
       simplex: true,
       smart: true,
       up: true },
    index: 8,
    mtu: 1500,
    ipv6: [ { address: 'fe80::48e:ceba:32c2:923c', prefixLength: 64 } ],
    ipv4:
     [ { address: '10.129.41.23',
         netmask: '255.255.255.0',
         broadcast: '10.129.41.255' } ],
    active: true },
  { hardwareAddress: '4e:98:56:5b:36:97',
    internal: false,
    name: 'awdl0',
    flags:
     { broadcast: true,
       multicast: true,
       promisc: true,
       running: true,
       simplex: true,
       up: true },
    index: 11,
    mtu: 1484,
    ipv6: [ { address: 'fe80::4c98:56ff:fe5b:3697', prefixLength: 64 } ],
    active: true } ]

interface

Each interface returned is an object with the following properties:

• active (required, Boolean) - indicates whether or not the interface is connected and actively transmitting data
• flags (optional, String) - a sub-document that provides additional detail regarding the interface and its hardware configuration
  • addrconf (optional, Boolean)
  • allmulti (optional, Boolean)
  • anycast (optional, Boolean)
  • broadcast (optional, Boolean)
  • cluif (optional, Boolean)
  • cos (optional, Boolean)
  • debug (optional, Boolean)
  • deprecated (optional, Boolean)
  • dhcp (optional, Boolean)
  • duplicate (optional, Boolean)
  • failed (optional, Boolean)
  • fixedmtu (optional, Boolean)
  • grouprt (optional, Boolean)
  • inactive (optional, Boolean)
  • loopback (optional, Boolean)
  • mip (optional, Boolean)
  • multibcast (optional, Boolean)
  • multicast (optional, Boolean)
  • multinet (optional, Boolean)
  • noarp (optional, Boolean)
  • nochecksum (optional, Boolean)
  • nofailover (optional, Boolean)
  • nolocal (optional, Boolean)
  • nonud (optional, Boolean)
  • nortexch (optional, Boolean)
  • notrailers (optional, Boolean)
  • noxmit (optional, Boolean)
  • oactive (optional, Boolean)
  • offline (optional, Boolean)
  • pfcopyall (optional, Boolean)
  • pointopoint (optional, Boolean)
  • preferred (optional, Boolean)
  • private (optional, Boolean)
  • pseg (optional, Boolean)
  • promisc (optional, Boolean)
  • quorumloss (optional, Boolean)
  • router (optional, Boolean)
  • running (optional, Boolean)
  • simplex (optional, Boolean)
  • smart (optional, Boolean)
  • standby (optional, Boolean)
  • temporary (optional, Boolean)
  • unnumbered (optional, Boolean)
  • up (optional, Boolean)
  • virtual (optional, Boolean)
  • varmtu (optional, Boolean)
  • xresolv (optional, Boolean)
• hardwareAddress (required, String) - the MAC address assigned to the interface
• index (optional, String) - on Darwin OS, this is functionality equivalent to metric... it is the prioritized order of the interface to the OS
• internal (required, Boolean) - indicates whether the interface exists for internal use within the OS (i.e. a loopback interface)
• ipv4 (optional, Array) - IPv4 address information for the interface
  • address (optional, String)
  • broadcast (optional, String)
  • netmask (optional, String)
• ipv6 (optional, Array) - IPv6 address information for the interface
  • address (optional, String)
  • prefixLength (optional, Number)
• metric (optional, Number) - the prioritized order of the interface to the OS
• mtu (optional, Number) - the maximum transmission unit size for the interface
• name (required, String) - the name assigned to the interface