From 5eaab2e99b6c477227eed59ec78dbcd7e1b0f4ff Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Mon, 13 Sep 2021 02:34:15 +0200 Subject: implement reconnect trick, bump version --- README.md | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index da92a72..65d2da9 100644 --- a/README.md +++ b/README.md @@ -12,26 +12,39 @@ The server only accepts one client at a time. The client auto-reconnects. ## Setting up a MITM debugging proxy -To debug stateful protocols on top of websockets, it is helpful to be able to -inject messages to the server or the client in a real session, acting as a -man-in-the-middle (MITM). On Linux you can achieve this using `webcat` and -FIFOs as follows: +By redirecting the standard input/output streams of webcat you can turn it into +a man-in-the-middle proxy, particularily useful for debugging stateful protocols +on top of websocket. + + [some client] <-> [webcat server] <-> [webcat client] <-> [some server] + FIFOs + +All it takes to set this up is four commands, for example: mkfifo client-in server-in webcat ws://example.com:3000/ < client-in > server-in webcat -l 4000 < server-in > client-in echo > server-in # unblock the FIFO deadlock -You can now connect your client to ws://localhost:4000/. -And inject messages by writing to the named pipes: +You can now connect your client to `ws://localhost:4000/` +and inject messages by writing to the named pipes: echo "Hello from webcat" > client-in -Note that when redirecting stdout the messages are automatically printed to -stderr, so you can still observe what's happening. +Webcat does two tricks to make this setup even more convenient: + +* When redirecting stdout, the messages are automatically printed + to stderr, so you can still observe what's happening. + +* When the client recognizes the server output `accepted new client`, + it automatically disconnects and reconnects its server connection + to prevent stateful application protocols from becoming out of sync. + ## Limitations +* no support for binary messages + * no support for messages containing newlines (cannot send them, cannot distinguish them from separate messages) -- cgit v1.2.3