Home

FAQ

What can tc-warpgate be used for?

a) To make sure that your tc configuration is working as expected! A nice visualization makes it a lot easier and more comfortable.
b) As an on-demand network traffic monitor/visualizer. Remember, it is not intended as a long-term monitoring solution, as tc-warpgate does not store any information on its own.

How does it work?

tc-warpgate is basically a HTML5/canvas frontend paired with a PHP backend. As you open it in your browser, the warpgate will fetch information and statistics directly from tc, parse them, and visualize them using javascript.

Do I have to configure tc-warpgate before using it?

Well, not really. See the installation instructions below. You might want to configure the webserver it is running on.

How does it actually look like?

Like this:

Better resolution

I have another question/concern that is not being answered! What do I do?

Have a look at the rest of the document, maybe the usage instructions might help you?
If not, you can write me an email!

Features

• realtime monitoring for tc
• visualization of qdiscs and classes (and htb rate and ceil)
• configurable interface-specific maximum throughput
• commenting qdiscs and classes
• view qdisc and class statistics
• persistent storage of user-defined settings

Caveats

• poor GUI performance on heavy traffic (reducing the particle count in warpgate.config.js may help)
• though there are some checks against malformed requests, I do not guarantee security in any way. Make sure only system admins or trusted users have access to tc-warpgate.
• currently, additional information is only processed for htb classes (you may add a ticket requesting special treatment of other classes, together with an example tc setup for testing purposes)
• tested only using pfifo_fast, pfifo, sfq and htb. Should also work for any other qdiscs / classes though.
• the UI is not suited for mobile devices.

Installation instructions

1. Install a webserver and php module on the server which should be monitored (if not already present)
   example (ubuntu): sudo apt-get update && sudo apt-get install apache2 php5
2. Copy all files from the repository to your webserver data directory
   example directory: /var/www/html/
3. make the config.json file writable for the webserver:
   example: sudo chown www-data /var/www/html/config.json && sudo chmod 644 /var/www/html/config.json
4. optionally customize the webserver based on your needs (e.g. switch to https)
5. finished! Open up the webservers address in a browser to start monitoring.

Usage instructions

Overview

The warpgate consists of two mayor parts:

• The interface header:
  Contains the currently selected interface name, its current throughput (2nd line) and its configured maximum throughput (3rd line).
• The warpgate itself:
  The warpgate contains multiple rings and ring segments, of which each represents a qdisc or class. The innermost ring represents the root qdisc. The more a ring segment is filled, the higher is the load of the particular qdisc or class. The higher the overall bandwidth usage is, the more particles will spawn and move to the center of the warpgate (dequeuing). Depending on the tc configuration, it may take a few seconds until the warpgate is fully build. Changes to the tc configuration will be reflected by the warpgate in realtime.

Navigation & Interaction

• Select the interface to be monitored:
  Move your cursor over the interface header. A list of all interfaces will be displayed. Simply click on any interface to select it and start monitoring it. Each interface has its own color, which will be applied to the whole warpgate upon selection. When you move to cursor away from the interfaces list, the list will disappear after a short period of time.
• Adjust the maximum interface throughput:
  By default, each interface has its maximum achievable throughput set to its link speed. This may be inappropriate under certain circumstances, for example, when an interface is used as a WAN interface but has a link speed of 1Gbps or 10Gbps.
  First, select the interface you want to edit as described in (1). Click on the maximum throughput of the selected interface (this is the 3rd line). An overlay will appear where you can enter the new maximum throughput. Be aware that it cannot be greater than the auto detected link speed. When saving, the entered maximum throughput will be stored on the server, which makes configuration necessary only once.
• Control the warpgate's viewport:
  Drag and drop the warpgate to move it around.
  Use the mousewheel or the scrollbar to zoom in and out.
• Display information about a qdisc/class:
  Move your cursor above a ring segment to display additional information and usage statistics about the corresponding qdisc/class.
• Expand a qdisc/class:
  Sometimes it is necessary to view a qdisc or class in greater detail, because its allocated display size is not large enough.
  Click on a ring segment (representing the qdisc/class) to expand it. Click on the expanded ring to retract it to its original size.
  Be aware that child classes/qdiscs will be expanded as well, while parent classes/qdiscs will be hidden.
  Once you have expanded a qdisc/class, you can expand its children as well. Note that you will have to retract each expanded element individually, beginning at the outermost element.
• Comment a qdisc/class:
  Double-click a ring segment to add or edit comments for the corresponding qdisc/class. An overlay will appear which enables you to enter a comment headline and text. The entered comments will be displayed alongside the information about the qdisc/class and will be stored on the server.

Interpreting information

• Warpgate structure:
  As mentioned above, the warpgate consists of multiple rings or ring segments, of which the innermost represents the root qdisc. Around it are ring segments representing classes of the root qdisc. Around those are qdiscs / child classes attached to those classes, and so on.
  You can distinguish qdiscs from classes by either looking at their name at the detail display (move the cursor above them!) or by their color. Classes are colored slightly darker than qdiscs.
  The size of each ring segment is derived from the element's ceil (if configured) or rate (if configured) or implicit rate (taken from its parent). If it is too small, expand it as described above.
• Usage visualization:
  Each ring segment is filled according to the qdisc's/class' current load. If it is empty (gray and only outline visible), no packets are traversing the qdisc/class. When being filled by the interface's color, the qdisc's/class' rate or implicit rate usage is being visualized; for example, if being halfway filled, 50% of the rate is being used at the moment. Additionaly, classes may be filled with a white color; if that happens, the class is exceeding its configured rate and is using its ceil! When being fully filled with a white color, the class is at 100% ceil usage. When being half way filled with a white color, the class uses 100% of its configured rate added to 50% of the difference between ceil and rate.

An example for this specific situation:
The class configuration contains a rate of 100kbps and ceil of 200kbps. When halfway filled with a white color, it is therefore using 100kbs + (50% * (200kbps-100kbps)) = 150kbps. Conclusion: Halfway filled means as much as using 50% of the speed in between ceil and rate.

• Detailed display:
  The following information will be displayed when hovering a qdisc/class:
  Note that all information are being updated frequently, close to realtime. All speeds are averaged over the last second (by default).