Terminalogy

Here're a list of terminalogies that would be repeatly used on this page. It's pretty easy to understand though.

• Loopback packets: packets send from localhost (ie 127.0.0.1) to localhost.
• Inbound packets: packets send in to your computer. It can be from somewhere else and also from your computer.
• Outbound packets: packets send out from your computer.
• Filtering: you often want to select a subset of interested network packets for clumsy to process. This is done by provide a filter to specify which IP, protocol, or other criterias.
• Capturing packets: clumsy needs to intercept the packets from your application so it can process it. So when your applicatioon is sending/receiving a packet, clumsy would capture it.
• Reinjecting packets: after we captured the packets, we need to let them of again so your application can get it. The process is called reinjecting.

Limitations

! Be sure you don't skip this part.

There's some issues with no easy workaround found. So here's a list of limitations that you should be aware of before using clumsy.

1. Loopback inbound packets can't be captured or reinjected.
   When you think about it, it's really difficult to tell it's an inbound or outbound packets when you're sending packets from the computer to itself. In fact the underlying Windows Filtering Platform seems to classify all loopback packets as outbound. The thing to remember is that when you're processing on loopback packets, you can't have "inbound" in your filter. It's important to know that your computer may have IPs other than 127.0.0.1, like an intranet IP allocated by your router. These are also considered loopback packets.
2. Loopback packets are captured twice.
   Since we don't have inbound loopback packets, all loopback packets are considered as outbound. So clumsy will process them twice: first time is when sending, and second time when receiving. A simple example is that when filter is simply "outbound", and apply a lag of 500ms. When you ping localhost, it would be a lag of 1000ms. You can work around it by specify destination port and things like this. But it would be easier to just keep this in mind and be careful when setting the parameters.
3. Inbound packet capturing is not working all the time.
   As previously noted, loopback inbound packets can't be reinjected. The problem is that on occasions some packets may be classified as inbound packets, even if the destination IP isn't of your computer. This only affects non-loopback packets. If you're only working on localhost it's going to be fine. The goal of future release is to diagnose what caused this and provide a solution.
4. Can't filter based on process
   System wide network capturing is listed as a feature. But really this is since there's no easy way to provide a robust solution.

How to use:

Download the release based on your Windows bitness. Remember 64bit system should use the 64bit one or it might not work at all. Another thing to note is that clumsy needs administrator privilege to run. clumsy will try to pop out the UAC dialogue. If it doesn't work then you should right click on the executable and choose "Run as Administrator". After clumsy starts up, the GUI should be pretty easy to grasp. Here's a screenshot:

In the order of numbered icons in the screenshot:

1. Filter input. The detailed syntax will be explained in next section. But it's just like bool expression in most programming language. Packets are captured based on this filter.
2. Presets. There's a list of builtin presets for you to choose. You can skim through to see what the filters can be like. And if you've get more familar with clumsy, you can add your own filters in config.txt bundled along the executable.
3. Control button. Click this to start capturing. In a few occasions it might fail. For example if your filter isn't syntatical right. In some occasions it might fail with other errors. See Faqs for more info. Once it's started the text would be changed to "Stop". There's a small icon on the left. When there's packets captured it would green. When there's failed rejecting the icon would turn red. When this happens it's mostly due to the limitations listed above. You should change your filter accordingly.
4. Function control. Tick the checkbox to enable functions. There's also an icon on the left side of the controls. It would turn green when this function is working. You can tick the checkbox anytime during the whole process and it would be toggled on and off as expected.
5. Parameters control. For each function there's some additionally control for you to tune. The most common ones are:
   • Inbound/Outbound: whether to process inbound/outbound packets. These are independent of the filter ones and allow you to change anytime.
   • Chance: the probability of this function to process. Obviously you don't want to drop packets all the time so you'd better set chances to a reasonable value.
6. Status: show some helpful text messages about the current state.

The functions should be self-explanatory. You can refer to the introduction for an overview, or just try it by your self. If you can't find something to test on, you can set filter to "tcp and outbound" and play with your broweser.

Filter Syntax

The filtering text is directly feed to WinDivert. The syntax is well documented here. If you've programmed in any language, it should be looks very familar to what you put in the if condition. You can use and, or, not and parentheses to build the logic expression. Ops like =, !=, ‹, › are also provided. A list of available fields from WinDivert documentation is attached as below. You can also refer to the presets for example.

Faqs

Failed to start with error code 3.
Run cmd and use these two lines:

            sc stop WinDivert1.0
            sc delete WinDivert1.0 
            

This will be addressed in future version.

clumsy introduces overhead to the network.
When you enter you filter and hit 'Start', clumsy has already started capturing packets. This would definetely add overhead into the network. Fortunately this is sort of consistent with the usage of this software. There is room for optimization, but it might need more work. It would be better to make your filters accurately capture the packets you're interested in.

Lag is much more higher than the parameter set.
The gist is that the parameters are not intended to be an accurate measure. It's more of a parameter to control the behavior. Another thing is that the lag introduced is on per network packet. For example if clumsy introduced 20ms lag on both incoming and outgoing packets. A TCP connection needs at least 3 packets to establish. Then it's a 3*20ms in total. In the example of a web page, it might need to finish some HTTP requests in sequence before it starts rendering in the browser. Say it needs to complete requests 1, 2 and 3. When each is slowed down by 60ms the time it takes to start rendering would be delayed by 3*60=180ms. So don't worry too much when clumsy makes things slow too much :)

Failed to start on Windows Server 2008.
This can be fixed by installing an patch from Microsoft. See this.

---