---
module: agent.packet-capture
title: Packet Capture — on-demand network capture for ATM diagnostics
tab: Internal
order: 20
audience: dev
---

> **Internal · ops/support view.** Confirmed against `hiveops-module-packet-capture` source 2026-07-01.

## What it does (and doesn't)

`hiveops-module-packet-capture` (module name `packet-capture`, class `PacketCaptureModule`) is **not** a passive monitor — it is a **fleet-task executor**. It sits idle polling for work and only runs `tcpdump`/`tshark`/`pktmon`/`netsh trace` when a `PACKET_CAPTURE` fleet task is queued for that ATM from **Fleet → Tasks** (`fleet.bcos.cloud`). There is no continuous packet monitoring, no baseline, no alerting from this module — it captures for a bounded window, uploads the file, and stops.

Flow at a glance:
1. Operator creates a `PACKET_CAPTURE` fleet task for one or more devices, with `duration` (seconds), `interface` (or "auto"), and an optional BPF `filter` (e.g. `tcp port 443`).
2. The agent's `packet-capture` module polls every **30s** for a pending task of kind `PACKET_CAPTURE`.
3. It runs the platform-appropriate capture tool for the requested duration (capped at **300s / 5 minutes** even if a larger value is requested).
4. The resulting file (`.pcap` or `.etl`) is uploaded back to the fleet task in chunks, then deleted from the ATM's local disk.
5. Fleet shows the task COMPLETED with a downloadable capture file (or FAILED with a reason).

## Config properties it registers

**None.** Unlike most agent modules there is no `packet-capture.*` properties namespace. The module reuses whichever of these is already configured:

| Key | Used for |
|-----|----------|
| `agent.endpoint` | Preferred base URL for polling tasks / uploading the capture (module picks this prefix first) |
| `incident.endpoint` | Fallback base URL if `agent.endpoint` is not set (older ATMs) |
| `agent.auth.token` / `agent.institution.key` | Auth for the same HTTP calls (shared with every other module) |

There is no way to tune poll interval, max duration, or upload chunk size via properties — they are hardcoded (`POLL_INTERVAL_SECONDS = 30`, `MAX_DURATION = 300`, `SEGMENT_SIZE = 100_000` bytes) in `PacketCaptureModule` / `PacketCaptureHandler`. If Fleet requests more than 300s, the agent silently clamps it — the task will still say "300s" in its running status, not the requested value.

## Enabled / deployed to ATMs

- **Enable condition:** the module self-enables whenever `agent.endpoint` **or** `incident.endpoint` is set — i.e. it's on by default on any normally-configured ATM. To turn it off for a specific ATM/institution, push `modules.disabled=packet-capture` (comma-separated list) via a `CONFIG_UPDATE` fleet task.
- **Shipped how:** it's one of the standard ATM module set built by `deployment/build-dist.sh` (module set `atm`, the default) — it ships in every standard ATM install/patch ZIP as `modules/hiveops-module-packet-capture.jar`, a drop-in JAR (not baked into the fat JAR). It is **excluded** from the `srv` module set (server-monitoring-only installs).
- **Retrofitting an ATM that doesn't have it yet:** deliver via a fleet `INSTALL_MODULE` task (drops the JAR into `modules/` and restarts the agent), or via a full agent update that includes the current module set.

## Common failure modes / what to check

| Symptom | Likely cause | What to check |
|---|---|---|
| Task stays PENDING forever | Agent's `packet-capture` module isn't running, or was disabled via `modules.disabled` | Confirm the module started in `logs/modules/packet-capture.log`; check `modules.disabled` on that ATM |
| Task fails immediately: "Another capture is already in progress" | A second `PACKET_CAPTURE` task landed on the same ATM while one was still running | Only one capture runs per ATM at a time (`captureInProgress` guard). Wait for the first to finish or cancel it |
| Task fails: "Capture produced no output — capture tool may require elevated privileges" | `tcpdump`/capture tool isn't allowed to open the interface (not running as root/Administrator, or interface doesn't exist) | Check the agent service's OS-level privileges; on Linux confirm `tcpdump` is installed (`apt-get install tcpdump`) |
| Task fails: "tcpdump is not installed" | Linux ATM is missing `tcpdump` | Install it; there's no fallback tool on Linux (Windows has tshark → pktmon → netsh) |
| Windows capture uses `.etl` instead of `.pcap` | `tshark` isn't installed/on PATH, so the agent fell back to `pktmon` or `netsh trace` (neither supports a BPF filter — captures everything) | Install Wireshark/tshark on the ATM if a filtered `.pcap` capture is required |
| Upload never completes / times out | Network issue mid-upload, or capture file very large for a slow link | Handler retries a stalled chunk up to 5 times before failing; check ATM network health and capture duration/size |
| Task shows COMPLETED but capture file missing locally | Expected — the local file is always deleted after upload (success or failure) to avoid leaving PCAPs (which may include unmasked traffic) on the ATM disk | Download the file from the Fleet task record, not the ATM |
| A different fleet task type (e.g. `LOG_COLLECT`) seems to interfere | The legacy `command-processor` module explicitly releases any `PACKET_CAPTURE` task it sees back to `PENDING` (with message "Released to packet-capture module") so the dedicated module can claim it — this is expected coordination, not a bug | If capture tasks never move past PENDING, confirm the `packet-capture` module (not just `command-processor`) is actually running |

## Not applicable here

This module has no journal/incident event integration — it does not emit `IAT_*` or any `EventType` events. Its only "reporting" is fleet task status (`RUNNING` / `COMPLETED` / `FAILED`) via the same status-report endpoint every fleet task uses.
