localaddress-agent

Node.js HTTP Agent to use IP addresses from a range for outgoing requests. Currently only Linux is supported!

Do you have a large number of IP addresses (e.g. a /64 IPv6 range assigned to your VPS) that you would like to use for outgoing requests? Assigning all of them to your network interface up front is not viable, as there are just too many; Assigning them in batches periodically is a bit unreliable as well, as you will have to coordinate the switch from one batch to another.

This package on the other hand

1. lets you specify a range (or an iterator, if you want more control) of IP addresses,
2. always keeps a configurable number of IP addresses assigned to the network interface (a pool),
3. removes them once they have been used often enough (once by default).

To assign & remove addresses from the network interfaces efficiently, this package uses the rtnetlink API via the awesome netlink npm package.

localaddress-agent then packages this IP address pool into an http.Agent/https.Agent (technically an agent-base@7 Agent) that, with each new HTTP request sent with it, assigns a new IP address as localAddress.

Installation

npm install localaddress-agent

Because localaddress-agent uses netlink underneath, on a typical Linux system, it needs these dependencies to be installed:

• python3
• make
• g++/GCC
• Linux headers

Usage

import {createIpPoolAgent} from 'localaddress-agent'
import http from 'http'

// endlessly cycle 30 IPv6 addresses
const ipAddresses = (function* () {
	let i = 0
	while (true) {
		yield `fe80::acab:${i.toString(16)}/64`
		i = ++i % 30
	}
})()

const agent = createIpPoolAgent(ipAddresses, 'enp0s8')

// send a lot of requests, with changing local addresses
for (let i = 0; i < 100; i++) {
	http.get('http://example.org/', {
		agent,
	}, cb)
}

API

createIpPoolAgent(ipAddresses, interface, opt = {})

ipAddresses must be an iterable or async iterable.

interface must be the name of a network interface (e.g. eth0) or its index.

Entries in opt override the following defaults:

• useExistingAddresses – Use addresses defined in ipAddresses if they are assigned to the network interface already? Default: true
• addressAssignTimeout – Timeout for assigning an IP address to the network interface. Default: 1s
• addressRemoveTimeout – Timeout for removing an IP address from the network interface. Default: 1s
• minAddresses – Minimum number of addresses to keep assigned/idle (once this amount has been reached once). Default: 10
• maxAddresses – Minimum number of addresses to keep assigned/idle. Default: 50
• addressMaxIdleTime – Time that assigned IP addresses have to be idle (unused) in order to be removed automatically. Default: 10m
• removeAddressesEvery – How often to check for "stale" idle IP addresses. Default: 10s

Related

• netlink npm package – netlink & rtnetlink client
• k13-engineering/node-rtnetlink – alternative to netlink
• C code from the Avahi project adding an address via rtnetlink

Contributing

If you have a question or need support using localaddress-agent, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, use the issues page.