Network Address

The netaddr module provides functions and the netaddr.range object type for parsing, validating and manipulating IP addresses, network prefixes and MAC addresses.

Address ranges are represented by netaddr.range instances which carry the address, its family and a prefix size (CIDR notation). Instances are created with the new(), IPv4(), IPv6() or MAC() functions:

import * as netaddr from 'netaddr';

const addr = netaddr.new('10.24.0.1/24');
const addr = netaddr.new('10.24.0.1/255.255.255.0');
const addr = netaddr.new('10.24.0.1', '255.255.255.0');  // separate netmask
const addr = netaddr.new('10.24.0.1/24', 16);            // override netmask

const addr6 = netaddr.new('fe80::221:63ff:fe75:aa17/64');
const addr6 = netaddr.new('fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::');

const mac = netaddr.new('00:11:22:cc:dd:ee');
const mac = netaddr.MAC('C0:B6:F9:00:00:00/24');

The checkv4(), checkv6() and checkmac() functions provide non-throwing validation, returning the canonical string representation of the given address or null if the argument is not a valid address of the respective family:

netaddr.checkv4('127.0.0.1');  // "127.0.0.1"
netaddr.checkv6('::1');        // "::1"
netaddr.checkmac('00:11:22:cc:dd:ee');  // "00:11:22:CC:DD:EE"
netaddr.checkv4('nonsense');   // null
Source

Classes

netaddr.range

Represents an IP address or address range as created by new(), v4(), v6() or mac().

Instances carry the address, its family (4 for IPv4, 6 for IPv6 and 1 for MAC addresses) and a prefix size in bits (32 for IPv4, 128 for IPv6 and 48 for MAC addresses by default).

Instances provide a tostring() method which is also used by print() and string interpolation to render the address in canonical form, including the prefix size if it is smaller than the family's full width.

In addition, instances support property access through __get__() and __set__() metamethods:

  • Numeric keys read or write the individual address bytes, e.g. addr[0] reads the first address byte and addr[0] = 10 rewrites it. Negative indices count from the end of the address.
  • The bits property reads or writes the prefix size in bits.
  • The family property reads the address family (numeric AF_* value).
  • The scope property reads or writes the address scope (the numeric interface index) for IPv6 and MAC address instances.
  • The scopeid property reads or writes the address scope given an interface name or numeric index, silently ignoring non-link-local IPv6 addresses.
  • The netmask property reads the netmask as a string, e.g. "255.255.255.0" for a /24 prefix.
  • The host property reads the host address as a new range (full-width prefix).
  • The mapped4 property reads the mapped IPv4 address as a new range, or null if the instance is not an IPv6 mapped IPv4 address.
  • The unscopename property reads the interface name of the address scope (or an empty string if no scope is set).
  • The size property reads the number of addresses in this range, or null if the value does not fit into a 64 bit signed integer.

Methods

checkmac(address) → {string}nullable

Verify an ethernet MAC address.

Checks whether the given argument is a preexisting netaddr.range MAC address instance or a string literal convertible to an ethernet MAC and returns a plain string containing the canonical representation of the address.

Returns null if the argument is not a valid MAC address. This function is intended to aid in safely verifying address literals without having to deal with exceptions.

Parameters:
NameTypeDescription
addressstring | range

A valid MAC address or existing netaddr.range MAC instance.

Returns: string
Example
netaddr.checkmac(netaddr.new('00-11-22-cc-dd-ee'));  // "00:11:22:CC:DD:EE"
netaddr.checkmac('00:11:22:cc:dd:ee');          // "00:11:22:CC:DD:EE"
netaddr.checkmac('nonsense');                   // null
netaddr.checkmac(123);                          // null
netaddr.checkmac(null);                         // null
Source

checkv4(address) → {string}nullable

Verify an IPv4 address.

Checks whether the given argument is a preexisting netaddr.range IPv4 address instance or a string literal convertible to an IPv4 address and returns a plain string containing the canonical representation of the address.

Returns null if the argument is not a valid IPv4 address. This function is intended to aid in safely verifying address literals without having to deal with exceptions.

Parameters:
NameTypeDescription
addressstring | range

A valid IPv4 address or existing netaddr.range IPv4 instance.

Returns: string
Example
netaddr.checkv4(netaddr.new('127.0.0.1'));  // "127.0.0.1"
netaddr.checkv4('127.0.0.1');          // "127.0.0.1"
netaddr.checkv4('nonsense');           // null
netaddr.checkv4(123);                  // null
netaddr.checkv4(null);                 // null
Source

checkv6(address) → {string}nullable

Verify an IPv6 address.

Checks whether the given argument is a preexisting netaddr.range IPv6 address instance or a string literal convertible to an IPv6 address and returns a plain string containing the canonical representation of the address.

Returns null if the argument is not a valid IPv6 address. This function is intended to aid in safely verifying address literals without having to deal with exceptions.

Parameters:
NameTypeDescription
addressstring | range

A valid IPv6 address or existing netaddr.range IPv6 instance.

Returns: string
Example
netaddr.checkv6(netaddr.new('0:0:0:0:0:0:0:1'));  // "::1"
netaddr.checkv6('0:0:0:0:0:0:0:1');          // "::1"
netaddr.checkv6('nonsense');                 // null
netaddr.checkv6(123);                        // null
netaddr.checkv6(null);                       // null
Source

mac(address, netmaskopt) → {range}

Construct a new MAC netaddr.range instance.

Raises a runtime exception if the given argument does not represent a valid ethernet MAC address or if the given optional mask is of a different family.

Parameters:
NameTypeDescription
addressstring | number | number[] | object

A valid ethernet MAC address, optionally with prefix size (CIDR notation) or mask separated by slash, an unsigned number representing the last 32 bit of the address, an array of exactly 6 bytes, or a sockaddr-like object with family AF_PACKET.

netmaskstring | number(optional)

A valid MAC address mask or a number containing a prefix size between 0 and 48 bit. Overrides the mask embedded in the first argument if specified.

Returns: range
Example
const intel_macs = netaddr.MAC('C0:B6:F9:00:00:00/24');
const intel_macs = netaddr.MAC('C0:B6:F9:00:00:00/FF:FF:FF:0:0:0');
const intel_macs = netaddr.MAC('C0:B6:F9:00:00:00', 'FF:FF:FF:0:0:0');
const intel_macs = netaddr.MAC('C0:B6:F9:00:00:00/24', 48);  // override mask
Source

new(address, netmaskopt) → {range}

Construct a new netaddr.range instance, auto-detecting the address family.

Raises a runtime exception if the given argument does not represent a valid address or if the given optional netmask is of a different family.

Parameters:
NameTypeDescription
addressstring | number | number[] | object

A valid IPv4 or IPv6 address, optionally with prefix size (CIDR notation) or netmask separated by slash, an unsigned number, an array of bytes, or a sockaddr-like object (see below). Numbers are interpreted as MAC addresses, except when used with the module:netaddr#v4 or module:netaddr#v6 constructors. The address family of byte arrays is determined by their length: 4 for IPv4, 6 for MAC and 16 for IPv6.

A sockaddr-like object has the following properties:

  • address (string, mandatory): the address value
  • family (number, optional): AF_INET (2), AF_INET6 (10) or AF_PACKET (17, MAC); guessed from address if omitted
  • interface (string|number, optional): scope for AF_INET6 addresses, either an interface name or index
netmaskstring | number(optional)

A valid IPv4 or IPv6 netmask or a number containing a prefix size in bits (0..32 for IPv4, 0..128 for IPv6). Overrides the mask embedded in the first argument if specified.

Returns: range
Example
const addr = netaddr.new('10.24.0.1/24');
const addr = netaddr.new('10.24.0.1/255.255.255.0');
const addr = netaddr.new('10.24.0.1', '255.255.255.0');  // separate netmask
const addr = netaddr.new('10.24.0.1/24', 16);            // override netmask

const addr6 = netaddr.new('fe80::221:63ff:fe75:aa17/64');
const addr6 = netaddr.new('fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::');

const mac = netaddr.new('00:11:22:cc:dd:ee');
const mac = netaddr.new(0x001122ccddeeff);

const addr = netaddr.new([ 10, 24, 0, 1 ]);          // IPv4
const addr6 = netaddr.new([ 0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1 ]);

const addr = netaddr.new({ address: '10.24.0.1' });  // family guessed
const addr = netaddr.new({ family: 2, address: '10.24.0.1' });
const addr6 = netaddr.new({ family: 10, address: 'fe80::1', interface: 'lo' });
Source

v4(address, netmaskopt) → {range}

Construct a new IPv4 netaddr.range instance.

Raises a runtime exception if the given argument does not represent a valid IPv4 address or if the given optional netmask is of a different family.

Parameters:
NameTypeDescription
addressstring | number | number[] | object

A valid IPv4 address, optionally with prefix size (CIDR notation) or netmask separated by slash, an unsigned number representing the address in host byte order, an array of exactly 4 bytes, or a sockaddr-like object with family AF_INET (or an address guessed as IPv4).

netmaskstring | number(optional)

A valid IPv4 netmask or a number containing a prefix size between 0 and 32 bit. Overrides the mask embedded in the first argument if specified.

Returns: range
Example
const addr = netaddr.IPv4('10.24.0.1/24');
const addr = netaddr.IPv4('10.24.0.1/255.255.255.0');
const addr = netaddr.IPv4('10.24.0.1', '255.255.255.0');  // separate netmask
const addr = netaddr.IPv4('10.24.0.1/24', 16);            // override netmask
Source

v6(address, netmaskopt, scopeopt) → {range}

Construct a new IPv6 netaddr.range instance.

Raises a runtime exception if the given argument does not represent a valid IPv6 address or if the given optional netmask is of a different family.

Parameters:
NameTypeDescription
addressstring | number | number[] | object

A valid IPv6 address, optionally with prefix size (CIDR notation) or netmask separated by slash, an unsigned number representing the last 32 bit of the address, an array of exactly 16 bytes, or a sockaddr-like object with family AF_INET6 (or an address guessed as IPv6), optionally carrying an interface scope.

netmaskstring | number(optional)

A valid IPv6 netmask or a number containing a prefix size between 0 and 128 bit. Overrides the mask embedded in the first argument if specified.

scopestring | number(optional)

An optional address scope for link-local addresses (fe80::/10), either an interface name or numeric index.

Returns: range
Example
const addr6 = netaddr.IPv6('fe80::221:63ff:fe75:aa17/64');
const addr6 = netaddr.IPv6('fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::');
const addr6 = netaddr.IPv6('fe80::221:63ff:fe75:aa17', 'ffff:ffff:ffff:ffff::');
const addr6 = netaddr.IPv6('fe80::221:63ff:fe75:aa17/64', 128);  // override
const addr6 = netaddr.IPv6('fe80::221:63ff:fe75:aa17', 64, 'eth0');
Source