Manage Directives

Directives are commands passed to Tawon Agents, through the Tawon Controller. A Directive is made of a series of Tasks, and optional Conditions. The Tasks pipeline must start with a Source Task, and usually ends with a Destination Task, with 0 or more Processing Tasks in between. Conditions allow to refine what machine, network interface, or process the Directives should run.

The tawonctl command can list, create, enable, disable, and destroy Directives. It also has utilities to simplify quick execution of a temporary Directive. Temporary Directives are created when the command is called and destroyed when the command quits.

Listing Directives

Get all Directives with:

tawonctl directives
topology is a special Directive that is started by default by Tawon Controller collect network topology information.

Creating Directives

Create a simple directive with:

tawonctl directives create -t "capture|filter:udp src port 53" -t "headers" -t "dns" -t "publish|topic:dns"

This Directive creates a disabled Directive with the following Tasks: * capture: Capture packets on all machine interfaces (specifying which interface to capture can be done with Conditions). This capture will only happen for UDP packets on port 53, thanks to a classic BPF filter.

By default, directives are not enabled. You will need to enable the directive with the enable subcommand, or pass the --enabled flag (or -e) to immediately enable the directive on creation.

Directive Kind

By default, directives created with tawonctl are applied by Tawon Agents.

Directives can also be used to configure Tawon Worker instances. To send a directive to Workers instead of Agents, pass the --worker (or -w).

To create directives that should be running on both Agents and Workers, use the -all flag.

Directive Task Options

Tasks passed to directive commands follow the --task flag (or -t for short). The task name comes first, followed by configuration options for the task. They are seperated from the task by a vertical bar (|), and from each other by semicolons (;). Finally, option name and value are separated by a colon (:).

task|optionA:valueA;optionB:valueB

See Tasks for a list of available tasks and their options.

Directive Conditions

Conditions passed to directive commands follow the --condition flag (or -c for short). The condition name and value are separated by a colon (:).

condition:value

If multiple --condition flags are passed they are OR-ed.

-c "conditionA:valueA" -c "conditionA:valueB"

Mutliple conditions can be found under one condition string using AND.

-c "conditionA:valueA AND conditionB:valueB"

Condition values will be matched exactly. You can do partial matches with modifiers.

If the value string starts with a tilde (~), the value should be contained in the matching condition. It is equavalent to the following regexp: .value..

condition:~value

Wild cards can be added anywhere in the string with an asterisk (): value is equivalent with value.. It can be placed in the middle of the string (and is non-greedy): val*ue (val.?ue).

condition:value*

Finally, full regular expressions can be used (following the "RE2 syntax"[https://github.com/google/re2/wiki/Syntax]) by prepending and append forward slashes to the value: /myproc-\d+/.

condition:/value-\d+/

See Tasks for a list of available tasks and their conditions.

Enable/Disable Directives

By default, on creation, Directives are disabled, meaning they exist in the system but are executed. You can enable and disable Directives at any time by ID.

Enable

Enable an existing directive with:

tawonctl directives enable bqtsgv3llsp2vks3g3qg

Disable

Disable an existing directive with:

tawonctl directives disable bqtsgv3llsp2vks3g3qg

Subscribing to Directives

tawonctl offers a simple method to subscribe to existing or temporary Directives without having to talk to the message queue directly.

Subscribing only works on directives with a publish task of type NATS.
Subscriptions using tawonctl is a convenience that should not be used continuously in production as all data produced by the Directive will be proxied through Tawon Controller, which is ineffecient, and will not scale well. It is most useful for testing and debugging purposes.

Subscribe to an Existing Directive by ID

If you know the ID of the directive you wish to inspect (see Listing Directives), you can subscribe to its output like so:

tawonctl directives sub bqtsgv3llsp2vks3g3qg

Subscribe to a Temporary Directive

You can create an subscribe to a temporary Directive that is created on the fly, and will get removed as soon as you terminate the command:

tawonctl directives sub -t "capture|filter:udp src port 443" -t "headers" -t "publish|topic:headers"

Deleting a Directive by ID with:

You can delete a Directive by ID with:

tawonctl directives rm bqtsgv3llsp2vks3g3qg

Other Functions

"Tap" a Directive

The same functions as sub exist in a tap version, where a dummy network device will be created on your machine and publish the packets collected. Only raw packet data should be collected with such a Directive.

Here are 2 examples, one with a tap by ID and one using a tap on a temporary Directive.

tawonctl directives tap bqtt8dkg7oq89ipnp5s0
tawonctl directives tap -t "capture|filter:udp src port 53" -t "publish|topic:packets"
In order to use the tap feature, only the capture and publish tasks should be specified. If other tasks are specified (e.g. dns), the whole packet will not be transmitted and we cannot supply the local interface with packets.

"Dump" a Directive

And a dump subcommand, works in the same manner as tap, but saves a pcap file. If passed a -f dump.pcap argument, it will save to the given file, otherwise it will pipe the data on stdout. Only raw packet data should be collected with such a Directive.

tawonctl directives dump -t "capture|filter:udp src port 53" -t "publish|topic:packets" -f dump.pcap
In order to use the dump feature, only the capture and publish tasks should be specified. If other tasks are specified (e.g. dns), the whole packet will not be transmitted and we cannot supply the dump file with packets.

"H2" a Directive

The h2 subcommand was created to provide a high level interface to task the system for h2 task. Behind the scenes, it executes 3 actions:

  1. Create a new directive with tlsplaintext/payload task, capture the raw messages and publish to a random topic;

  2. Read from this random topic and write them to a file;

  3. Subscribe to this random topic to consume these messages, decode them as h2 and pretty print the h2 messages on screen;

The goal is to make ease the debug, because we capture the raw messages (tlsplaintext/payload) meanwhile the h2 messages are produced. Previously, when some error occurred inside the h2 message, we would need to rerun the test again just to collect the tlsplaintext/payload message.