Active Capture File Support

Overview

Active Capture File Support is an experimental feature that enables PacketViewer to monitor and display packets from capture files that are still being written to disk by another process (such as tcpdump or other capture tools). This allows users to analyze network traffic in near real-time while a capture is ongoing, without needing to stop the capture process.

When enabled, PacketViewer continuously polls the capture file and automatically displays new packets as they’re appended, providing an experience similar to watching a live capture while maintaining full access to all PacketViewer features including display filters, custom columns, protocol trees, and follow stream.

How It Works

When a capture file is opened in active capture mode:

1. PacketViewer loads the initial packets from the file
2. The system continuously polls the file every 2 seconds
3. When new packets are detected, they’re automatically appended to the packet list
4. The backend API server uses the Linux inotify feature to detect when the file has been modified
5. When a file change is detected, any open sessions are closed and reopened on the next request
6. This cycle continues until the capture is stopped, the file is closed, or a maximum of 500,000 packets is read.

As new packets arrive, the packet list automatically scrolls to show the most recent packets. If you select a packet to examine it, auto-scrolling stops to let you review the selected packet without interruption. When you’re ready to return to monitoring new packets, click the “Resume” button in the status bar to jump back to the most recent packets and resume auto-scrolling.

All standard PacketViewer functionality remains available during active capture, including display filters, custom columns, packet tree analysis, and follow stream.

Important Limitations and Caveats

Active Capture File Support is an experimental feature with several important limitations that users should be aware of:

Performance Limitations

1. Re-parsing overhead: The entire file is re-parsed from the beginning each time new data is detected. As the capture file grows larger, this becomes increasingly inefficient and can eventually cause the system to fall behind the rate at which new packets are being written.

2. Not suitable for long-running captures: Due to the re-parsing behavior, this feature works best for shorter capture sessions or troubleshooting scenarios with lower per-second packet rates. Extended captures will eventually become too large to process efficiently.

3. Server-side processing: All parsing work is done by the sharkd backend process, which can impact server performance during active captures.

Platform Requirements

1. inotify dependency: This feature relies on Linux’s inotify system to detect file changes. If inotify is not available or supported, the feature may not work correctly.

2. File system requirements: The capture file must be on a file system that supports proper file change notifications. URLs are not supported.

3. File must exist: The capture file must already exist when the PacketViewer component loads. If the component is loaded before the file exists, it will not automatically refresh when the file is created.

Data Integrity

1. Append-only: This feature only works correctly if the capture file is being appended to. If existing packets in the file are modified or replaced, the behavior is undefined.

2. Packet truncation: Depending on how the capture tool flushes data to disk, packets may appear truncated or incomplete temporarily.

Feature Limitations

1. Follow Streams not updated: TCP/UDP stream following and other stream-based analysis features are loaded, but not automatically updated as new packets arrive. These features require a refresh to include newly captured data.

2. Analysis tools require refresh: Most analysis tools that depend on the complete contents of the file (such as conversation statistics, protocol hierarchy, etc.) will show incomplete data and require manual refresh to update.

3. NavChart not available: The NavChart component is not available when Active Capture mode is enabled, as it requires a complete file.

4. Limited status bar information: The status bar shows reduced information in Active Capture mode. Some fields may display incomplete or stale data as the file grows, and certain statistics are not available until the capture is complete.

Use Cases

Despite these limitations, Active Capture File Support is valuable for several scenarios:

• Real-time troubleshooting: Monitor network traffic as you reproduce an issue, without needing to stop and restart captures
• Short debugging sessions: Capture and analyze specific network behaviors in real-time during testing
• Continuous monitoring: Keep an eye on specific types of traffic using display filters while a capture runs
• Protocol development: Watch protocol exchanges happen in real-time while developing or testing new network applications

Best Practices

To get the most out of Active Capture File Support:

1. Keep captures short: Stop and restart captures periodically to avoid performance degradation from large files
2. Use bpf capture filters: Apply filters when capturing traffic to reduce the amount of data being processed and displayed
3. Monitor server resources: Watch CPU and memory usage on the API server during active captures
4. Plan for refresh: Avoid, or be prepared to manually refresh analysis tools and stream-based features when needed

Enabling Active Capture Mode

To enable Active Capture mode in your application, set the enableActiveCapture prop to true on the PacketViewer component:

import React from "react";
import { PacketViewer } from "@qacafe/pv-react";
import "@qacafe/pv-react/style.css";

function App() {
  return (
    <PacketViewer
      file="/path/to/capture.pcap"
      endpoint="/api"
      enableActiveCapture={true}
    />
  );
}

When enabled, PacketViewer will automatically poll the capture file every 2 seconds and display new packets as they’re appended to the file.