valence/crates/packet_inspector

What's This?

The packet inspector is a Minecraft proxy for viewing the contents of packets as they are sent/received. It uses Valence's protocol facilities to display packet contents. This was made for three purposes:

• Check that packets between Valence and client are matching your expectations.
• Check that packets between vanilla server and client are parsed correctly by Valence.
• Understand how the protocol works between the vanilla server and client.

Usage

Firstly, we should have a server running that we're going to be proxying/inspecting.

cargo r -r --example conway

Next up, we need to run the proxy server, this can be done in 2 different ways, either using the GUI application (default) or using the --nogui flag to log the packets to a terminal instance.

To assist, --help will produce the following:

A simple Minecraft proxy for inspecting packets.

Usage: packet_inspector [OPTIONS] [CLIENT_ADDR] [SERVER_ADDR]

Arguments:
  [CLIENT_ADDR]  The socket address to listen for connections on. This is the address clients should connect to
  [SERVER_ADDR]  The socket address the proxy will connect to. This is the address of the server

Options:
  -m, --max-connections <MAX_CONNECTIONS>
          The maximum number of connections allowed to the proxy. By default, there is no limit
      --nogui
          Disable the GUI. Logging to stdout
  -i, --include-filter <INCLUDE_FILTER>
          Only show packets that match the filter
  -e, --exclude-filter <EXCLUDE_FILTER>
          Hide packets that match the filter. Note: Only in effect if nogui is set
  -h, --help
          Print help
  -V, --version
          Print version

To launch in a Gui environment, simply launch packet_inspector[.exe] (or cargo r -r -p packet_inspector to run from source). The gui will prompt you for the CLIENT_ADDR and SERVER_ADDR if they have not been supplied via the command line arguments.

In a terminal only environment, use the --nogui option and supply CLIENT_ADDR and SERVER_ADDR as arguments.

cargo r -r -p packet_inspector -- --nogui 127.0.0.1:25566 127.0.0.1:25565

The client must connect to localhost:25566. You should see the packets in stdout when running in --nogui, or you should see packets streaming in on the Gui.

The -i and -e flags accept a regex to filter packets according to their name. The -i regex includes matching packets while the -e regex excludes matching packets. Do note that -e only applies in --nogui environment, as the Gui has a "packet selector" to enable/disable packets dynamically. The -i parameter value will be included in the Filter input field on the Gui.

For instance, if you only want to print the packets Foo, Bar, and Baz, you can use a regex such as ^(Foo|Bar|Baz)$ with the -i flag.

cargo r -r -p packet_inspector -- --nogui 127.0.0.1:25566 127.0.0.1:25565 -i '^(Foo|Bar|Baz)$'

Packets are printed to stdout while errors are printed to stderr. If you only want to see errors in your terminal, direct stdout elsewhere.

cargo r -r -p packet_inspector -- --nogui 127.0.0.1:25566 127.0.0.1:25565 > log.txt

Quick start with Vanilla Server via Docker

Start the server

docker run -e EULA=TRUE -e ONLINE_MODE=false -d -p 25565:25565 --name mc itzg/minecraft-server

View server logs

docker logs -f mc

Server Rcon

docker exec -i mc rcon-cli

In a separate terminal, start the packet inspector.

cargo r -r -p packet_inspector -- --nogui 127.0.0.1:25566 127.0.0.1:25565

Open Minecraft and connect to localhost:25566.

Clean up

docker stop mc
docker rm mc