README.md

🔗 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

Platform	TCP_KEEPINTVL	TCP_KEEPCNT	TCP_USER_TIMEOUT
🐧 linux	✅	✅	✅
🍏 osx	✅	✅	✅ (TCP_RXT_CONNDROPTIME)
😈 freebsd	✅	✅	❌
🐄 win32	➖	➖	➖

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!