{"id":11438,"library":"node-netstat","title":"Node.js Netstat Utility","description":"node-netstat is a JavaScript utility library designed to programmatically read and parse `netstat` data on various operating systems. It is currently at version 1.9.0 and provides a callback-based API for processing network connection information line by line. The library supports filtering results by properties like PID or protocol and offers both synchronous and asynchronous execution. Key differentiators include its cross-platform compatibility (tested on Ubuntu 14.04/16.04, Windows 7, and OS X Yosemite), extensibility via custom parsers and filters, and the ability to cancel ongoing `watch` operations. While `netstat` itself is considered obsolete on some Linux systems in favor of `ss`, node-netstat provides a unified interface for accessing this data where available, making it suitable for system monitoring and debugging tools in Node.js environments.","status":"active","version":"1.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/danielkrainas/node-netstat","tags":["javascript","netstat","utility"],"install":[{"cmd":"npm install node-netstat","lang":"bash","label":"npm"},{"cmd":"yarn add node-netstat","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-netstat","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library primarily uses CommonJS `require()` syntax. There is no explicit ESM export listed in the README, so direct ES module import might not work without a transpiler or Node.js loader configuration.","wrong":"import netstat from 'node-netstat';","symbol":"netstat","correct":"const netstat = require('node-netstat');"},{"note":"To customize platform-specific parsers, like enabling process name parsing for Linux, access them via the `netstat` object. This pattern is for modifying internal behavior rather than direct import.","wrong":null,"symbol":"netstat.parsers.linux","correct":"const netstat = require('node-netstat');\nnetstat.parsers.linux = netstat.parserFactories.linux({ parseName: true });"},{"note":"The library version is exposed as a property on the main `netstat` object, not as a separate import.","wrong":null,"symbol":"netstat.version","correct":"const netstat = require('node-netstat');\nconsole.log(netstat.version);"}],"quickstart":{"code":"const netstat = require('node-netstat');\n\n// Get network connections, filtering by a specific PID and protocol,\n// limiting the results to the first 5 entries.\nnetstat({\n  filter: {\n    pid: process.env.TARGET_PID ? parseInt(process.env.TARGET_PID) : 1, // Example PID, adjust as needed\n    protocol: 'tcp'\n  },\n  limit: 5,\n  done: (err) => {\n    if (err) {\n      console.error('Netstat command failed:', err);\n      return;\n    }\n    console.log('Netstat command completed.');\n  }\n}, function (data) {\n  // Process each line of netstat data\n  console.log('Netstat item:', data);\n\n  // Example: stop processing after finding a specific state\n  if (data.state === 'ESTABLISHED') {\n    console.log('Found an ESTABLISHED connection, stopping further processing.');\n    return false; // Returning false stops the stream\n  }\n});","lang":"javascript","description":"This quickstart demonstrates how to use `node-netstat` to asynchronously retrieve and filter network connection data. It shows how to apply filters for PID and protocol, limit the output, handle errors with the `done` callback, and conditionally stop processing results early from within the line handler function."},"warnings":[{"fix":"Set `parseName: true` when initializing the Linux parser factory for `netstat.parsers.linux` to include process names in the output.","message":"The `parseName` option for the Linux parser is `false` by default. If you require `processName` in your results on Linux, you must explicitly enable it by reconfiguring the parser via `netstat.parsers.linux = netstat.parserFactories.linux({ parseName: true });`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your `handler` function only returns `false` when you explicitly want to stop processing the stream of netstat results. Otherwise, omit an explicit return or return `true`.","message":"Returning `false` from the `handler` function will immediately stop processing any further netstat results. This is a design feature for early termination but can be a gotcha if not intended, potentially leading to incomplete data collection.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that the `netstat` utility is available and correctly installed on the target system. For new projects or critical applications, consider alternatives that use newer tools like `ss` or `procfs` for network statistics if `node-netstat` encounters issues on a specific OS version.","message":"On some modern Linux distributions, the `netstat` command-line utility is considered obsolete and `ss` is the recommended replacement. While `node-netstat` wraps the `netstat` command, its underlying reliability might be affected by system-level changes or deprecations of the `netstat` command itself. Ensure `net-tools` (which provides `netstat`) is installed on Linux systems if you encounter issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Store the return value of `netstat()` when using `watch: true`. Call `handler.cancel()` to stop the watching process when it's no longer required, typically in cleanup routines or when the application is shutting down.","message":"When using the `watch` option for continuous monitoring, the `netstat` function returns a handler object with a `cancel()` method. Forgetting to call `cancel()` when monitoring is no longer needed can lead to resource leaks or indefinitely running processes.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the `net-tools` package on Linux (e.g., `sudo apt-get install net-tools` or `sudo yum install net-tools`) or ensure the `netstat` executable's directory is included in the system's PATH environment variable on Windows or other OS. Alternatively, verify if the `platform` option is correctly set if overriding `os.platform()`.","cause":"The `netstat` command-line utility is not found in the system's PATH. This often occurs on minimal Linux installations or Windows systems where `netstat.exe` might not be readily accessible to Node.js.","error":"Error: spawn netstat ENOENT"},{"fix":"Check the `node-netstat` GitHub issues for known compatibility problems with your specific OS version. If no solution is available, consider contributing a fix or using a different system monitoring tool. Temporary workarounds might involve adjusting `filter` options or inspecting the raw `netstat` output to identify parsing discrepancies.","cause":"Specific operating system versions (like MacOS Sonoma) might have changes in `netstat` output or behavior that `node-netstat`'s parsers are not yet equipped to handle, leading to incomplete or incorrect results.","error":"Netstat is not finding a running localhost on MacOS Sonoma."}],"ecosystem":"npm"}