🔗 net-keepalive

ℹ️ Since libuv v1.35.0 (Node v13.12.0 & v12.17.0) both TCP_KEEPINTVL and TCP_KEEPCNT have somewhat predictable values This package allows you to tweak those values per each socket but at a cost of having to deal with FFI overhead and it's dependencies. Check the latest node docs for socket.setKeepaliveEnable, if the default values are good enough for you then you don't need to use this package.

The Missing (TCP_KEEPINTVL and TCP_KEEPCNT) SO_KEEPALIVE socket option setters and getters for Node using FFI.

Tested on 🐧 linux & 🍏 osx (both amd64 and arm64), should work on 😈 freebsd and others. Installs on 🐄 win32 🎉 but methods are no-ops (pull requests welcome).

There's also support for getting & setting the TCP_USER_TIMEOUT (🐧 linux and 🍏 osx only) option, which is closely related to keep-alive.

Platform support

Legend:

• ✅ - Supported
• ➖ - No operation
• ❌ - Unsupported (throws)

Install

npm install --save net-keepalive

Documentation

You can find the full API Reference Document (JSDoc) published on our github pages.

The project includes TypeScript definitions file (index.d.ts) which gives an overview of the API exposed.

Documentation gets generated from JSDoc comments, feel free to improve them by sending pull requests.

Demo

const Net = require('net'),
  NetKeepAlive = require('net-keepalive')
// or
import * as Net from 'net'
import * as NetKeepAlive from 'net-keepalive'

// Create a TCP Server
const srv = Net.createServer((s) => {
  console.log('Connected %j', s.address())
  // Doesn't matter what it does
  s.pipe(s)
})

// Start on some port
srv.listen(1337, () => {
  console.log('Listening on %j', srv.address())
})

// Connect to that server
const s = Net.createConnection({ port: 1337 }, () => {
  console.log('Connected to %j', s.address())

  //IMPORTANT: KeepAlive must be enabled for this to work
  s.setKeepAlive(true, 1000)

  // Set TCP_KEEPINTVL for this specific socket
  NetKeepAlive.setKeepAliveInterval(s, 1000)

  // Get TCP_KEEPINTVL for this specific socket
  NetKeepAlive.getKeepAliveInterval(s) // 1000

  // Set TCP_KEEPCNT for this specific socket
  NetKeepAlive.setKeepAliveProbes(s, 1)

  // Get TCP_KEEPCNT for this specific socket
  NetKeepAlive.getKeepAliveProbes(s) // 1
})

Now using iptables add rule to drop all tcp packets on INPUT chain to port 1337.

iptables -I INPUT -m tcp -p tcp --dport 1337 -j DROP

If you were monitoring packets on loopback with tcp.srcport == 1337 || tcp.dstport == 1337 filter in wireshark. You will see the following output:

Have fun!

More info about SO_KEEPALIVE here: TCP Keepalive HOWTO C Code examples here: Examples

Sample

_Note: For these methods to work you must enable SO_KEEPALIVE and set the TCP_KEEPIDLE options for socket using Net.Socket-s built in method socket.setKeepAlive([enable][, initialDelay]) !_

TCP_KEEPIDLE (since Linux 2.4) The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes, if the socket option SO_KEEPALIVE has been set on this socket. This option should not be used in code intended to be portable.

const NetKeepAlive = require('net-keepalive')
// or
import * as NetKeepAlive from 'net-keepalive'

// .....

const enable = true                                             // enable SO_KEEPALIVE
const initialDuration = 1000                                    // start probing after 1 second of inactivity
socket.setKeepAlive(enable, initialDuration)                    // sets SO_KEEPALIVE and TCP_KEEPIDLE

const probeInterval = 1000                                      // after initialDuration send probes every 1 second
NetKeepAlive.setKeepAliveInterval(socket, probeInterval)        //sets TCP_KEEPINTVL

const maxProbesBeforeFail = 10                                  // after 10 failed probes connection will be dropped
NetKeepAlive.setKeepAliveProbes(socket, maxProbesBeforeFail)    // sets TCP_KEEPCNT

// ....

Code of Conduct

See CODE_OF_CONDUCT.md

Contributing

See CONTRIBUTING.md

Contributors ✨

Thanks goes to these wonderful people (emoji key):

George Hertz 🚧 💻 📖 ⚠️ 📦 💬	Alba Mendez 💻 📖 ⚠️	Paulo Castro 🐛	Jacob Jewell 🐛	RMutharaju 🛡️	Rafael Borges 🐛	Calvin 🐛
ggsubs 🐛	Mario Kozjak 🐛	Lukas Knuth 💻	Ivan 🐛	Otávio Jacobi 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.20 (2025-06-08)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.12 (#375) (197873c)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.19 (2025-04-03)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.10 (#367) (d41225d)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.18 (2025-03-08)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.8 (#365) (47d51f5)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.17 (2025-03-01)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.6 (#361) (f07e8d2)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.16 (2025-02-09)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.5 (#359) (aba6be1)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.15 (2025-01-25)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.4 (#357) (30b2a41)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.14 (2025-01-14)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.3 (#355) (f554253)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.13 (2025-01-09)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.2 (#354) (6d72e72)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.12 (2024-12-24)

Bug Fixes

• deps: update dependency ffi-rs to v1.2.1 (#352) (e2a6a56)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.11 (2024-12-09)

Bug Fixes

• deps: update dependency ffi-rs to v1.1.1 (#344) (a8b36a5)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.10 (2024-09-23)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.96 (#340) (7fde6b9)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.9 (2024-09-19)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.95 (#338) (6025cdc)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.8 (2024-09-14)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.94 (#337) (0c60c0d)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.7 (2024-09-12)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.93 (#336) (df17ce4)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.6 (2024-08-29)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.91 (#333) (b1b191f)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.5 (2024-08-13)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.90 (#332) (0546694)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.4 (2024-08-04)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.89 (#331) (e8519ae)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.3 (2024-08-01)

Bug Fixes

• deps: update dependency ffi-rs to v1.0.88 (#329) (001e2ed)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.2 (2024-07-31)

Bug Fixes

• deps: update all dependencies (#319) (bfdc85b)
• deps: update dependency ffi-rs to v1.0.79 (#321) (e64adae)
• deps: update dependency ffi-rs to v1.0.81 (#322) (bb2024f)
• deps: update dependency ffi-rs to v1.0.82 (#323) (5681bad)
• deps: update dependency ffi-rs to v1.0.83 (#324) (370be6a)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.1 (2024-04-15)

Bug Fixes

• expose errorno from ffi-rs (#316) (27012c1)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

4.0.0 (2024-04-12)

⚠ BREAKING CHANGES

• use ffi-rs instead to support node 20.11+ versions (#314)

Bug Fixes

• use ffi-rs instead to support node 20.11+ versions (#314) (a75f33c)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

3.0.1 (2023-09-13)

Bug Fixes

• bump node verions (67dee2a)
• install tcpdump (aacb8c2)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

3.0.0 (2021-08-11)

⚠ BREAKING CHANGES

• win32: allow install and just no-op unsupported operations (#288)

Features

• win32: allow install and just no-op unsupported operations (#288) (6a6f9b8)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.1.0 (2021-07-03)

Features

• user-timeout: use TCP_RXT_CONNDROPTIME on darwin (#263) (dc15397)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.0.5 (2021-05-31)

Bug Fixes

• deps: bump ref-napi from 3.0.2 to 3.0.3 (#240) (65df449)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.0.4 (2021-04-06)

Bug Fixes

• deps: bump y18n from 4.0.0 to 4.0.1 (#207) (187be56)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.0.3 (2021-03-19)

Bug Fixes

• deps: bump ffi-napi from 4.0.2 to 4.0.3 (#201) (72b05a8)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.0.2 (2021-03-18)

Bug Fixes

• deps: bump ref-napi from 3.0.1 to 3.0.2 (#200) (b11bc27)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.0.1 (2021-03-13)

Bug Fixes

• deps: bump ffi-napi from 4.0.1 to 4.0.2 (#196) (3407889)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

2.0.0 (2021-02-24)

⚠ BREAKING CHANGES

• deps: bump ffi-napi from 3.1.0 to 4.0.1 (#180)

Bug Fixes

• deps: bump ffi-napi from 3.1.0 to 4.0.1 (#180) (1f24c04)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

1.4.0 (2020-11-09)

Features

• add support for the TCP_USER_TIMEOUT option (51462f7)

Bug Fixes

• requires node >=10.20.0 instead of >=4 (b8fe01c)
• temp monkey patch to allow tests to pass (ref: #93) (4cb944e)
• throw in (set|get)ters when constant == null (b5f1ce4)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

1.3.9 (2020-09-11)

Bug Fixes

• deps: bump node-fetch from 2.6.0 to 2.6.1 (#70) (84aba59)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

1.3.8 (2020-08-31)

Bug Fixes

• deps: bump ref-napi from 3.0.0 to 3.0.1 (#63) (5e094d1)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

1.3.7 (2020-08-13)

Bug Fixes

• deps: bump ref-napi from 2.0.4 to 3.0.0 (#48) (df56f7c)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

1.3.6 (2020-07-19)

Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning, enforced with semantic-release.

1.3.5 (2020-07-19)