Node.js Netstat Utility

Common errors

• Error: spawn netstat ENOENT

  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.
  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()`.

• Netstat is not finding a running localhost on MacOS Sonoma.

  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.
  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.

Warnings

• gotcha 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 });`.
  Fix: Set `parseName: true` when initializing the Linux parser factory for `netstat.parsers.linux` to include process names in the output.
• gotcha 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-netstat npm
• yarn add node-netstat yarn
• pnpm add node-netstat pnpm

Imports

• netstat
  wrong:

  import netstat from 'node-netstat';

  correct:

  const netstat = require('node-netstat');

  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.
• netstat.parsers.linux

  const netstat = require('node-netstat');
  netstat.parsers.linux = netstat.parserFactories.linux({ parseName: true });

  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.
• netstat.version

  const netstat = require('node-netstat');
  console.log(netstat.version);

  The library version is exposed as a property on the main `netstat` object, not as a separate import.

Quickstart

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.

const netstat = require('node-netstat');

// Get network connections, filtering by a specific PID and protocol,
// limiting the results to the first 5 entries.
netstat({
  filter: {
    pid: process.env.TARGET_PID ? parseInt(process.env.TARGET_PID) : 1, // Example PID, adjust as needed
    protocol: 'tcp'
  },
  limit: 5,
  done: (err) => {
    if (err) {
      console.error('Netstat command failed:', err);
      return;
    }
    console.log('Netstat command completed.');
  }
}, function (data) {
  // Process each line of netstat data
  console.log('Netstat item:', data);

  // Example: stop processing after finding a specific state
  if (data.state === 'ESTABLISHED') {
    console.log('Found an ESTABLISHED connection, stopping further processing.');
    return false; // Returning false stops the stream
  }
});