haraka-net-utils

This module provides network utility functions.

Usage

const net_utils = require('haraka-net-utils')`

ip_to_long

// Convert IPv4 to long
const long = net_utils.ip_to_long('11.22.33.44') // 185999660

long_to_ip

// Convert long to IPv4
const ip = net_utils.long_to_ip(185999660) // 11.22.33.44

dec_to_hex

// Convert decimal to hex
const hex = net_utils.dec_to_hex(20111104) // 132df00

hex_to_dec

// Convert hex to decimal
const dec = net_utils.hex_to_dec('132df00') // 20111104

normalize_ip

Normalizes an IPv4 or IPv6 address to canonical form. Returns null for invalid input. IPv4-mapped IPv6 addresses are converted to IPv4.

net_utils.normalize_ip('1.2.3.4') // '1.2.3.4'
net_utils.normalize_ip('0000:0000:0000:0000:0000:0000:0000:0001') // '::1'
net_utils.normalize_ip('::ffff:127.0.0.1') // '127.0.0.1'
net_utils.normalize_ip('not-an-ip') // null

is_local_ipv4

// Is IPv4 address on a local network?
net_utils.is_local_ipv4('127.0.0.200') // true (localhost)
net_utils.is_local_ipv4('169.254.0.0') // true (link local)
net_utils.is_local_ipv4('226.0.0.1') // false

is_private_ipv4

// Is IPv4 address in RFC 1918 reserved private address space?
net_utils.is_private_ipv4('10.0.0.0') // true
net_utils.is_private_ipv4('192.168.0.0') // true
net_utils.is_private_ipv4('172.16.0.0') // true

is_local_ipv6

// Is IPv6 addr on local network?
net_utils.is_local_ipv6('::1') // true (localhost)
net_utils.is_local_ipv6('fe80::') // true (link local)
net_utils.is_local_ipv6('fc00::') // true (unique local)
net_utils.is_local_ipv6('fd00::') // true (unique local)

is_private_ip

Determines if an IPv4 or IPv6 address is on a "private" network. For IPv4, returns true if is_private_ipv4 or is_local_ipv4 are true For IPv6, returns true if is_local_ipv6 is true

is_local_host

Checks to see if a host name matches our server hostname or resolves to any local ip. Local IPs include those bound to a local network interface and public IPs discovered with STUN.

is_local_ip

Checks to see if an IP is bound locally or an IPv4 or IPv6 localhost address.

ip_in_list

// searches for 'ip' as a hash key in the list object or array
// ip can be a host, an IP, or an IPv4 or IPv6 range
net_utils.ip_in_list(object, ip)
net_utils.ip_in_list(array, ip)
net_utils.ip_in_list(tls.no_tls_hosts, '127.0.0.5')

getHostIPs

Returns an array of all the IPv4 and IPv6 addresses of the provided hostname. The returned promise resolves with arrays of addresses and errors.

const { addrs, errors } = await net_utils.getHostIPs('host.example.com')

get_ips_by_host

Returns an array of all the IPv4 and IPv6 addresses of the provided hostname. The returned promise resolves with a (possibly empty) array.

try {
  const ips = await net_utils.get_ips_by_host(domain)
  for (const ip of ips) {
    // do something with the IPs
  }
  catch (errors) {
    for (const err of errors) {
      console.error(err)
    }
  }
}

// Callback form exposes lookup errors:
net_utils.get_ips_by_host(domain, (errors, ips) => {
  if (errors.length) {
    /* DNS errors */
  }
})

parse_proxy_line

Parses an HAProxy PROXY protocol v1 line. Accepts the full line (PROXY TCP4 …) or the payload after the command word (TCP4 …, as Haraka passes to cmd_proxy). Strips a trailing newline if present. Returns null for invalid or unsupported lines (including UNKNOWN).

net_utils.parse_proxy_line('PROXY TCP4 127.0.0.1 127.0.0.2 42310 465')
// {
//   type: 'haproxy',
//   proto: 'TCP4',
//   src_ip: '127.0.0.1',
//   src_port: '42310',
//   dst_ip: '127.0.0.2',
//   dst_port: '465',
// }

net_utils.parse_proxy_line('TCP6 ::1 ::1 2525 25') // same shape, proto: 'TCP6'
net_utils.parse_proxy_line('UNKNOWN 1.2.3.4 1.2.3.4 2525 25') // null

is_haproxy_allowed

Returns whether a connecting IP is allowed to send the HAProxy PROXY command, based on connection.ini [haproxy] settings. The IP is normalized before matching. Hosts may be listed as exact addresses or CIDR ranges. Returns false when HAProxy is disabled, the IP is invalid, or no host entry matches (including an empty hosts[] list).

Configure in config/connection.ini:

[haproxy]
enabled = true
hosts[] = 10.0.0.1
hosts[] = 10.0.0.0/24
hosts[] = 2001:db8::1

net_utils.is_haproxy_allowed('10.0.0.1') // true if listed or in a matching CIDR
net_utils.is_haproxy_allowed('8.8.8.8') // false
net_utils.is_haproxy_allowed('::ffff:10.0.0.1') // true when 10.0.0.1 is listed

get_mx

try {
  const mxList = await net_utils.get_mx(domain)
  for (const mx of mxList) {
    // do something with each mx
  }
} catch (err) {
  // handle any errors
}

HarakaMx

An object class representing a MX. HarakaMx objects may contain the following properties:

{
  exchange: '', // required: a FQDN or IP address
  path: '', // the file path to a socket
  priority: 0, // integer, a MX priority.
  port: 25, // integer: an alternate port
  bind: '', // an outbound IP address to bind to
  bind_helo: '', // an outbound helo hostname
  using_lmtp: false, // boolean, specify LMTP delivery
  auth_user: '', // an AUTH username (required if AUTH is desired)
  auth_pass: '', // an AUTH password (required if AUTH is desired)
  auth_type: '', // an AUTH type that should be used with the MX.
  from_dns: '', // the DNS name from which the MX was queried
}

Create a HarakaMx object in The Usual Way:

const nu = require('haraka-net-utils')
const myMx = new nu.HarakaMx(parameter)

The parameter can be one of:

• A string in any of the following formats:
  • hostname
  • hostname:port
  • IPv4
  • IPv4:port
  • IPv6
• A URL string
  • smtp://mail.example.com:25
  • lmtp://int-mail.example.com:24
  • smtp://user:[email protected]:587
• An object, containing at least an exchange, and any of the other properties listed at the top of this section.

An optional second parameter is an alias for from_dns.