Pixelflut, but with ICMP.
The reference implementation is split up into three Rust crates:
pingxelflut: Common data structures and utilities for writing Rust pingxelflut implementations. May be published to crates.io at some point.client: Simple client implementation.server: Reasonably performant server implementation.
The client has a few options controlling how and where to send images, see its --help output. It needs to be able to open raw sockets, which requires the cap_net_raw capability on Linux. (Alternatively, run it as root.)
![WARNING] Currently, the client does not properly work on Windows: It crashes your system. The root cause of this issue is not know, since the client can seemingly send packets over raw sockets just fine. Additionally, it cannot receive more than one echo reply, meaning that requesting the canvas size does not work.
The server does not have any options currently. It opens a window displaying the pingxelflut canvas; closing the window ends the application. The server also needs raw socket capabilities, so cap_net_raw seems to be required for Linux capabilities. (It doesn’t seem to be possible to run the server as root due to it interacting with the windowing system.)
![NOTE] The server is not tested on Windows.
For development, this command chain seems to be useful:
# in the `server` directory
cargo build --release && sudo setcap cap_net_raw=eip ../target/release/server && ../target/release/serverpyngxelflut - A simple but slooooooow (IPv6 only) implementation in Python, mostly there for me to learn more about ICMP(v6
Please open a PR to add your implementation!
RFC 2119 keywords are used in the following and MUST be interpreted accordingly.
The pingxelflut protocol is a layer 5 protocol based on ICMP (RFC 792) and any implementation MUST follow ICMP protocol requirements.
Messages to the server are sent as Echo Request packets (ICMP type 8 code 0, ICMPv6 type 128), messages to the client are sent as Echo Reply (ICMP type 0 code 0, ICMPv6 type 129).
Clients SHOULD use lowest-priority QoS (DSCP CS1, value 8) in the IP Traffic Class header. Servers SHOULD drop packets that do not conform to this lowest traffic class, and clients SHOULD expect that any server will do so.
The first four bytes of the payload are to be used according to Echo conventions. The first 16-bit word specifies the Echo request identifier, and the second 16-bit word specifies the Echo request sequence number. The identifier MUST be ignored. The sequence number of consecutive packets SHOULD be increasing.
The fifth byte of the payload specifies the packet type.
| Byte | Type | Direction |
|---|---|---|
| aa | Size request | To Server |
| bb | Size response | To Client |
| cc | Set pixel | To Server |
All multi-byte values are in network order (big endian). (Since the color bytes are defined individually below, their byte order is RGB(A) and not BGR or else.)
Byte numbers in the following refer to the byte indices after the packet type byte.
The size request packet contains no further data. The server responds with a size response packet. Size request packets MAY be rate-limited.
The size response packet contains the server’s canvas size as two unsigned 16-bit integers.
| Bytes | Value |
|---|---|
| 0-1 | Width |
| 2-3 | Height |
The set pixel packet contains an X and Y position to set a pixel at, plus an RGB(A) color to set. The coordinates are unsigned 16-bit integers, and the origin is in the top left corner of the image. The alpha value is optional.
| Bytes | Value |
|---|---|
| 0-1 | X position |
| 2-3 | Y position |
| 4 | Red |
| 5 | Green |
| 6 | Blue |
| 7 | Alpha (optional) |
The set pixel packet has no response.
- Servers SHOULD silently discard pixel setting requests that fall outside the defined canvas. They MAY wrap pixel setting requests at the image borders (
x mod widthandy mod height). - Since many systems can’t prevent default responses from ICMP Echo Request packets, any packet type that is invalid for its direction MUST be discarded by either side and not treated as an error.
- Any other kind of generally malformatted data MUST be discarded silently. Clients SHOULD warn the user about such events, for example to aid in debugging server implementations and raising issues with servers run at large events.
- Some network stacks may be ill-equipped to handle large amounts of ICMP packets. The Windows network stack has in testing shown to be one such example. Extra care needs to be taken when using such systems as part of a network that handles pingxelflut traffic.
- ICMP has no congestion control. Since clients can’t automatically decrease their sending rate, it is therefore recommended to silently drop ICMP packets in routers when the bandwidth limit is reached.
- ICMP cannot address applications, and on most operating systems any application receiving ICMP packets will recieve all ICMP packets sent to its machine (or at least to a specific link). While this does not limit the protocol itself (the only response message applies to all clients equally and may be read by anyone, even those that did not request it), it is therefore challenging to either run multiple clients on one machine, or to run a client on the same machine as a server. Additionally, running multiple distinct servers on one machine under one target IP address is not possible, but running a subordinate server that passively reads out pixel commands targeted at a main server may be useful.