NPM Node OS Codecov CI Dependencies Code Quality License

All Contributors

🔗 net-keepalive


The Missing (TCP_KEEPINTVL and TCP_KEEPCNT) SO_KEEPALIVE socket option setters and getters for Node using ffi-napi module.

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

🐧 linux
😈 freebsd
🐄 win32


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


npm install --save net-keepalive


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.


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

// 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:

Wireshark screenshot KEEPALIVE

Have fun!

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


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




Contributors ✨

Thanks goes to these wonderful people (emoji key):

George Hertz

🚧 💻 📖 ⚠️ 📦 💬

Alba Mendez

💻 📖 ⚠️

Paulo Castro


Jacob Jewell




Rafael Borges






Mario Kozjak


Lukas Knuth


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