Add `cf pcap` command to facilitate multi-instance packet captures

[maxmoehl]

Introduce a new cf pcap command that captures network traffic directly from running application container instances via SSH. This provides operators and developers with a native way to debug networking issues without needing to manually SSH into containers and perform the packet capture.

This is part of RFC0048.

Motivation

With the new cf-pcap feature in diego, app developers can perform packet captures themselves without privileged support from the operator (if enabled). Currently, this requires an understanding of the implementation details of these packet captures which should not be the case. The user should be able to perform packet captures through the same interface as all the other actions, hence a new CLI command. Since this a core feature of diego I opted for a built-in command as opposed to a plugin.

Proposed Changes

New command: cf pcap

cf pcap APP_NAME [--process PROCESS] [-i INDEX]
   [-o OUTPUT_FILE] [--filter FILTER] [--interface INTERFACE]
   [--snaplen SNAPLEN] [--skip-host-validation]

Flags:

Flag	Default	Description
--process	web	App process type to capture from
-i, --app-instance-index	all instances	Specific instance index (omit to capture from all running instances)
-o, --output	capture.pcap	Output file path
--filter	(none)	BPF filter expression passed to cf-pcap
--interface	eth0	Network interface to capture on
--snaplen	0 (cf-pcap default)	Snapshot length for captured packets
-k, --skip-host-validation	false	Skip SSH host key validation

Behavior:

• Requires an org and space to be targeted
• When -i is omitted, captures from all instances simultaneously
• Opens SSH connections to each target instance and runs /tmp/lifecycle/cf-pcap remotely
• Streams pcap-formatted data over SSH stdout, parses individual packets using gopacket, and merges packets from all instances into a single output .pcap file
• Capture runs until the user presses Ctrl-C, at which point SIGINT is forwarded to the remote processes and the SSH sessions are torn down after a 5-second grace period
• Displays the output file path and size on completion

To allow merging the packet streams the github.com/gopacket/gopacket dependency needs to be added. I intend to only use the pure Go parts (no cgo) to keep building / installing the CLI simple.

[metskem]

Sounds like a very useful feature. We currently offer packet capturing for our developers, but we had to build quite some gitops to be able to do it. This could be ditched if they can do it with just "cf pcap".
Thanks!

[maxmoehl]

Glad to hear that! Since the feature is already in diego you should be able to use it directly while I'm trying to get the CLI side ready. I'm currently looking for some feedback on the feature as I expect some bugs are still hidden in there so please give it a spin and report back with any issues.

[metskem]

When using the cf-pcap, I get:

/tmp/lifecycle/cf-pcap -interface lo 'port 8080'
time=2026-03-11T15:15:43.589+01:00 level=ERROR msg="failed to set up capture" error="failed to open device lo: lo: You don't have permission to perform this capture on that device (Attempt to create packet socket failed - CAP_NET_RAW may be required)"

Does it require privileged containers?

[maxmoehl]

No, we have a dedicated flag for this in rep, did you set this property? If setting this property does not help, please open an issue on diego-release and ping me in.