docs/development/debugging/packet_capture.md

# Packet Capture on Fuchsia

Packet capture is a fundamental tool for developing, debugging, and testing
networking.

Fuchsia provides target-side packet capturing capabilities via the **`net`**
CLI tool (part of `net-cli`).

## Running the `ffx net capture` plugin on the host

> Warning: **Host Tool Deprecation (`fx sniff`)**:
> `fx sniff` which is a host-side script that wraps running `tcpdump` on the
> target is a deprecated workflow. The new `net capture` CLI tool currently only
> supports rolling packet captures and does not yet support streamed mode,
> but unless streaming packet captures to see the output in real time is
> necessary, the newer `net capture` should be preferred as it provides
> better ergonomics.

The `ffx net capture` host plugin allows managing rolling captures directly from your
development host.

### Start a rolling capture

```shell
[host] $ ffx net capture start-rolling name:lo
```

You can optionally specify a packet filter using standard
[pcap-filter] syntax,
just like for `tcpdump` or `tshark`. See the help string for other arguments
that the start command takes or the [README] for more examples.

The default, minimum, and maximum buffer sizes are defined in [FIDL], and the
resulting rolling packet capture will contain as many of the most recently
captured packets that fit the negotiated buffer size. The `--snap-len` argument
can also be used so that only the first N bytes of each packet is captured
instead of the entire packet, which can help fit more packets into the capture
since the contents of the payload is often not relevant.

### Stop and download a rolling capture

```shell
[host] $ ffx net capture stop-rolling
```

This stops the capture, downloads the accumulated packet capture directly
to your development host, and prints the path on the host where the pcapng
file has been saved.

## Running the `net` binary on the target directly

In order to run the `net` tool on the target directly, ensure
`//src/connectivity/network/net-cli` is included in your build.

Usage is otherwise virtually identical to the ffx plugin.

```shell
[target] $ net capture start-rolling name:lo
[target] $ net capture stop-rolling
```

## Running `tcpdump` on the target directly

Ensure that `//third_party/tcpdump` is included in your build so that `tcpdump`
can be run on the target directly.

## Reference: `fx` workflow packet signatures
There are many different kinds of services running between the Fuchsia
development host and the target. Those are usually invoked by `fx` commands.
Most of times, you are not interested in those packets generated by the `fx`
workflows. The following table lists noteworthy signatures.

| Use                  | Signature                    | Reference                                  |
|----------------------|------------------------------|--------------------------------------------|
| fx shell             | port 22                      | devshell/shell                             |
| SSDP                 | port 1900                    | UPnP discovery traffic                     |
| zxdb (legacy)        | port 2345                    | Legacy raw TCP debug agent connection      |
| mDNS                 | port 5353                    | Dynamic target discovery                   |
| Package Server       | port 8083                    | docs/packages.md                           |
| Logger               | port 33337                   | NETBOOT_DEBUGLOG_PORT_SERVER               |
| Logger               | port 33338                   | NETBOOT_DEBUGLOG_PORT_ACK                  |
| Bootserver           | port 33330                   | NETBOOT_PORT_SERVER                        |
| Bootserver           | port 33331                   | NETBOOT_PORT_ADVERT                        |
| Bootserver           | port 33332                   | NETBOOT_PORT_CMD_START                     |
| Bootserver           | port 33339                   | NETBOOT_PORT_CMD_END                       |
| Bootserver           | port 33340                   | NETBOOT_PORT_TFTP_OUTGOING                 |
| Bootserver           | port 33341                   | NETBOOT_PORT_TFTP_INCOMING                 |
| target netsvc addr   | fe80::xxxx:xxff:fexx:xxxx%XX | fx device-finder list --netboot            |
| host link-local addr | fe80::xxxx:xxxx:xxxx:xxxx%XX | fx device-finder list --ipv4=false --local |
| target netstack addr | fe80::xxxx:xxxx:xxxx:xxxx%XX | fx get-device-addr                         |


[pcap-filter]: https://www.tcpdump.org/manpages/pcap-filter.7.html
[FIDL]: /sdk/fidl/fuchsia.net.debug/packet_capture.fidl
[README]: /src/connectivity/network/net-cli/README.md