traffico

2022-05-24T00:00:00+00:00
traffico is a collection of tools to shape traffic on a network using traffic control tc(8)</code>. It can be used via a CLI tool (traffico</code>) or as a CNI plugin (traffico-cni</code>). For a list of the available programs and what they do see the Built-in programs</a> section.</p>
The built-in programs are very opinionated and made for the needs of the authors but the framework is flexible enough to be used for other purposes. You can add programs to the bpf/</code> directory to extend it to other use cases.</p>
Contact§</a>
</h2>
If you have problems, questions, ideas or suggestions, please contact us by
posting to https://github.com/leodido/traffico/issues.</p>
Download§</a>
</h2>
To download the very latest source do this:</p>
git</span> clone https://github.com/leodido/traffico.git</span></span></code></pre>Authors§</a>
</h2>

Leonardo Di Donato</li>
Lorenzo Fontana</li>
</ul>
Usage§</a>
</h2>
Traffico can be either used standalone or as a CNI plugin.</p>
traffico§</a>
</h3>
traffico</code> is a CLI tool that can be used to load and unload the programs.
You can choose an interface and choose whether the program will be loaded in
INGRESS</code> or EGRESS</code>.</p>
Start with a standalone block program when the policy targets specific traffic
and should leave everything else alone:</p>
traffico</span> --ifname=eth0 --at=INGRESS</span> block_private_ipv4</span></span></code></pre>
Programs that accept runtime input (marked [input]</code> in --help</code>) take it as a second positional argument:</p>
traffico</span> --ifname=eth0</span> block_ipv4</span> 10.0.0.1</span></span>
traffico</span> --ifname=eth0</span> block_port</span> 443</span></span></code></pre>
Use standalone allow programs when the interface should admit only the traffic
described by that one program:</p>
traffico</span> --ifname=eth0</span> allow_ipv4</span> 10.0.0.10</span></span>
traffico</span> --ifname=eth0</span> allow_proto tcp+udp</span></span>
traffico</span> --ifname=eth0</span> allow_ethertype ipv4+arp</span></span></code></pre>
Use --chain</code> when the policy needs multiple ordered stages. Chains that contain
L3/L4 programs must start with the L2 gate allow_ethertype</code>:</p>
traffico</span> --ifname=eth0 --chain</span> "allow_ethertype:ipv4+arp,allow_port:443"</span></span></code></pre>
Chains compose checks linearly: each stage narrows the traffic that reaches the
next stage. That works well for single-path policies such as HTTPS to one
service:</p>
traffico</span> --ifname=eth0 --at=EGRESS --chain</span> \</span></span>
  "allow_ethertype:ipv4+arp,allow_ipv4:10.0.0.10,allow_proto:tcp,allow_port:443"</span></span></code></pre>
Or DNS to one resolver:</p>
traffico</span> --ifname=eth0 --at=EGRESS --chain</span> \</span></span>
  "allow_ethertype:ipv4+arp,allow_dns:10.0.0.53"</span></span></code></pre>
These examples are alternative linear policies, not an additive multi-flow
allowlist. Full policies such as "DNS to resolver OR HTTPS to service" need
explicit OR composition.</p>
Chain order is validated before attach. If a chain contains any L3/L4 program,
slot 0 must be allow_ethertype</code>, and the layer order must be L2 -> L3 -> L4</code>.</p>
traffico-cni§</a>
</h3>
traffico-cni</code> is a meta CNI plugin that allows the traffico programs to be used in CNI.</p>
Meta means that traffico-cni</code> does not create any interface for you,
it is intended to be used as a chained CNI plugin.</p>
The plugin block to use traffico-cni</code> is very similar to how traffico</code> is
used as a CLI tool.</p>
{</span></span>
    "type"</span>:</span> "traffico-cni"</span>,</span></span>
    "program"</span>:</span> "block_private_ipv4"</span>,</span></span>
    "attachPoint"</span>:</span> "ingress"</span></span>
}</span></span></code></pre>
Programs that accept runtime input use the "input"</code> field:</p>
{</span></span>
    "type"</span>:</span> "traffico-cni"</span>,</span></span>
    "program"</span>:</span> "block_ipv4"</span>,</span></span>
    "input"</span>:</span> "10.0.0.1"</span>,</span></span>
    "attachPoint"</span>:</span> "egress"</span></span>
}</span></span></code></pre>
Here's an example CNI config file featuring traffico-cni</code>.</p>
{</span></span>
    "name"</span>:</span> "mynetwork"</span>,</span></span>
    "cniVersion"</span>:</span> "0.4.0"</span>,</span></span>
    "plugins"</span>: [</span></span>
        {</span></span>
            "type"</span>:</span> "ptp"</span>,</span></span>
            "ipMasq"</span>:</span> true</span>,</span></span>
            "ipam"</span>: {</span></span>
                "type"</span>:</span> "host-local"</span>,</span></span>
                "subnet"</span>:</span> "10.10.10.0/24"</span>,</span></span>
                "resolvConf"</span>:</span> "/etc/resolv.conf"</span>,</span></span>
                "routes"</span>: [</span></span>
                    {</span> "dst"</span>:</span> "0.0.0.0/0"</span> }</span></span>
                ]</span></span>
            },</span></span>
            "dns"</span>: {</span></span>
                "nameservers"</span>: [</span>"1.1.1.1"</span>,</span> "1.0.0.1"</span>]</span></span>
            }</span></span>
        },</span></span>
        {</span></span>
            "type"</span>:</span> "firewall"</span></span>
        },</span></span>
        {</span></span>
            "type"</span>:</span> "traffico-cni"</span>,</span></span>
            "program"</span>:</span> "block_private_ipv4"</span>,</span></span>
            "attachPoint"</span>:</span> "ingress"</span></span>
        },</span></span>
        {</span></span>
            "type"</span>:</span> "tc-redirect-tap"</span></span>
        }</span></span>
    ]</span></span>
}</span></span></code></pre>Design principles§</a>
</h2>
Principle</th> Description</th></tr></thead>

Standalone vs chained</td> Standalone programs are the only filter on the interface and handle all traffic types themselves. Chained programs pass traffic they do not handle to the next program, trusting that an upstream filter (typically allow_ethertype</code>) already constrained it.</td></tr>
Boundary failures</td> block_*</code> programs fail open (TC_ACT_OK</code>) on truncated headers, unsupported protocols, and subsequent fragments because they target specific traffic. allow_*</code> programs fail closed (TC_ACT_SHOT</code>) on the same failures because they define permitted traffic.</td></tr>
L2 → L3 → L4 ordering</td> Chains run cheapest and broadest checks first: allow_ethertype</code> (L2), then allow_proto</code> (L3), then allow_port</code> or allow_dns</code> (L4). allow_ipv4</code> fits after L2 and alongside or after L3 protocol filtering.</td></tr>
Non-IPv4 passthrough in chains</td> In chains, L3 and L4 programs pass non-IPv4 traffic to the next program via tail_call_next()</code>. L2 filtering is allow_ethertype</code>'s job; ARP, IPv6, and other non-IPv4 traffic allowed by L2 must not be silently dropped downstream.</td></tr>
</tbody></table>
Built-in programs§</a>
</h2>
Program</th> Description</th></tr></thead>

allow_dns</code></td> Allows IPv4 DNS traffic (TCP/UDP port 53) to the input resolver. Other IPv4 traffic passes through. Standalone mode blocks non-IPv4; chain mode passes non-IPv4 to the next stage.</td></tr>
allow_ethertype</code></td> L2 gatekeeper: drops frames whose outer EtherType is not in the allowed set (e.g., ipv4+arp</code>). Required first when a chain contains L3/L4 programs.</td></tr>
allow_ipv4</code></td> Allows IPv4 traffic to the input address, drops other IPv4 destinations except localhost (127.0.0.0/8). Standalone mode blocks non-IPv4; chain mode passes non-IPv4 to the next stage.</td></tr>
allow_port</code></td> Allows IPv4 TCP/UDP traffic to the input port. Other IPv4 protocols pass through. Standalone mode blocks non-IPv4; chain mode passes non-IPv4 to the next stage. TCP/UDP subsequent fragments are blocked.</td></tr>
allow_proto</code></td> L3 gatekeeper: drops IPv4 packets whose IP protocol is not in the allowed set (e.g., tcp+udp</code>). It unwraps supported VLAN/QinQ tags before the IPv4 protocol check. Standalone mode blocks non-IPv4 after VLAN unwrap; chain mode passes it to the next stage.</td></tr>
block_private_ipv4</code></td> Blocks private IPv4 addresses subnets allowing only SSH access on port 22</td></tr>
block_ipv4</code></td> Drops packets with destination equal to the input IPv4 address</td></tr>
block_port</code></td> Drops packets with the destination port equal to the input port number</td></tr>
nop</code></td> A simple program that does nothing</td></tr>
</tbody></table>
Notes on allow_ethertype</code>§</a>
</h3>
Chain ordering:</strong> If a chain contains any L3/L4 program, slot 0 must be allow_ethertype</code>. Chain order must be non-decreasing by layer: L2 -> L3 -> L4</code>. Same-layer programs are allowed, and chains may skip L3 after the L2 gate, such as --chain "allow_ethertype:ipv4+arp,allow_port:443"</code>.</p>
VLAN-tagged networks:</strong> Standalone allow_ethertype</code> compares the EtherType in the outer Ethernet header only; it does not unwrap VLAN tags or match the inner payload EtherType. Symbolic names vlan</code> (0x8100) and qinq</code> (0x88A8) are available for standalone filters. In multi-program chains, VLAN TPIDs are rejected because VLAN-aware parsing is not uniform across downstream programs. Example (standalone): allow_ethertype ipv4+arp+vlan</code>.</p>
Notes on allow_proto</code>§</a>
</h3>
Chain ordering:</strong> In a chain, allow_proto</code> should be placed after allow_ethertype</code> and before allow_port</code>/allow_dns</code>. This gives L2 -> L3 -> L4</code> ordering with cheapest checks first. Example: --chain "allow_ethertype:ipv4+arp,allow_proto:tcp+udp,allow_port:8080"</code>.</p>
VLAN-tagged IPv4:</strong> allow_proto</code> unwraps supported 802.1Q and QinQ tags before reading the IPv4 protocol. Truncated VLAN headers and unsupported additional VLAN nesting fail closed.</p>
Non-IPv4 behavior:</strong> In standalone mode, non-IPv4 traffic is blocked after VLAN unwrap because the program is the complete policy. In chain mode, non-IPv4 traffic is passed to the next stage because L2 policy belongs to allow_ethertype</code>.</p>
Build§</a>
</h2>
To compile traffico from source you either provide your vmlinux.h</code> in the
vmlinux/</code> directory (default option) or you configure the project to
generate one from your current Linux kernel:</p>
xmake</span> f</span> --generate-vmlinux=y</span></span></code></pre>
Now you will be able to build traffico from source by running:</p>
xmake</span></span></code></pre>
In case you only want to compile the BPF programs you can do this:</p>
xmake</span> -b</span> bpf</span></span></code></pre>Test§</a>
</h2>
To run the test suite you can do this:</p>
xmake</span> -b</span> test</span></span>
xmake</span> run test</span></span></code></pre>
The full test suite includes Scapy-backed advanced packet tests that exercise IP options, fragmentation, and protocol-specific behavior. These require the python-scapy</code> (Arch) or python3-scapy</code> (Ubuntu) package. If Scapy is not installed, the advanced tests are skipped automatically.</p>
leodido.dev - Shell

traffico

Download§</a> </h2> To download the very latest source do this:</p> git</span> clone https://github.com/leodido/traffico.git</span></span></code></pre>Authors§</a> </h2> Leonardo Di Donato</li>

Authors§</a> </h2> Leonardo Di Donato</li>
