Tillered Docs

Appearance

UniFi Firewall Configuration with Tillered ​

UniFi’s Gateway and Router solutions, including the UDM-Pro, are primarily consumer-focused but support advanced networking features through manual CLI configuration. Integrating Tillered Nodes into your UniFi deployment enables intelligent traffic routing, directing specific traffic flows through designated exit nodes for optimized performance and enhanced administrative control. Due to the limited UI capabilities, these configurations must be implemented manually via SSH and the CLI.

Example Network Overview ​

This guide follows an example network setup to illustrate how to configure Tillered with a UniFi gateway. Your actual network setup may differ, and adjustments should be made accordingly.

Network Components: ​

  • Source Host (Client Device): 172.16.220.10 (Connected to VLAN 220)

  • UniFi Gateway (UDM-Pro): Routes traffic and applies policy-based routing

  • Tillered Entry Node: 172.16.110.42 (Connected to VLAN 110)

  • VLAN 220: Internal client network (172.16.220.0/24)

  • VLAN 110: Tillered network (172.16.110.0/24) for routing external traffic

  • Internet / External Network: Final destination for routed traffic

Network Diagram ​

Prerequisites ​

  • SSH Access to UniFi Device: Ensure root SSH access is enabled on your UniFi gateway or router. To enable SSH access, navigate to the UniFi Controller, go to Settings > Control Plane > Console > Advanced, and enable SSH. Note the SSH username and password or key-based authentication details required for access.

  • Tillered Entry Node: Obtain the IP address of the Tillered Entry Node to be used as the gateway.

Step 1: Establish an SSH Connection ​

Access your UniFi device via SSH to begin configuration.

sh
ssh root@<your_UniFi_Device_IP>

Step 2: Define a Custom Routing Table ​

Modify the routing tables file to register a custom routing table for Tillered.

sh
echo "220 vlan220_table" >> /etc/iproute2/rt_tables

  • 220 is an example VLAN ID used in this configuration. The actual VLAN ID should match the client's network setup.

  • vlan220_table is a custom name for the routing table and can be adjusted as needed for the specific deployment.

Step 3: Configure a Route for the Custom Routing Table ​

Define a default route within the custom routing table, directing traffic through the Tillered Entry Node.

sh
ip route add default via <tillered_entry_node_ip> dev <interface_name> table <custom_table>

  • Replace <tillered_entry_node_ip> with the Tillered Entry Node's IP.

  • Replace <interface_name> with the appropriate network interface (e.g., br110). You can find the correct interface by running:

NOTE

sh
ip link show

This will list all network interfaces on the UniFi device. The correct interface is typically associated with the VLAN or network where the Tillered Entry Node resides.

  • Replace <custom_table> with the custom routing table name from Step 2.

Example:

shell
ip route add default via 172.16.110.42 dev br110 table vlan220_table

Step 4: Define Policy-Based Routing Rules for Source Traffic ​

Policy-based routing (PBR) allows you to direct specific traffic through a designated route based on its source IP or subnet, rather than relying on traditional destination-based routing. In this setup, we define rules that ensure outbound traffic from specific devices or entire subnets is routed through the Tillered Entry Node for optimized external connectivity. By implementing these rules, we can create flexible traffic flow strategies that meet various network requirements.

sh
ip rule add from <source_ip_or_subnet> lookup <custom_table>

  • Replace <source_ip_or_subnet> with either a single IP (e.g., 172.16.220.10) or an entire subnet (e.g., 172.16.220.0/24).

  • Replace <custom_table> with the custom routing table name from Step 2.

Example:

sh
# Apply policy-based routing for a single host
ip rule add from 172.16.220.10 lookup vlan220_table

# Apply policy-based routing for the entire VLAN 220 subnet
ip rule add from 172.16.220.0/24 lookup vlan220_table

By applying this rule to an individual host, such as 172.16.220.10, we ensure that only this specific device's outbound traffic is directed through the Tillered Entry Node. Alternatively, applying the rule to an entire subnet like 172.16.220.0/24 enforces this routing for all devices within VLAN 220. This flexibility allows administrators to fine-tune traffic flows, ensuring that only the necessary traffic is directed through the Tillered infrastructure while maintaining standard routing for other hosts.

Step 5: (Optional) Exclude Specific Traffic from Routing ​

To exempt certain destinations or source IPs from the custom routing table, exclusion rules can be applied. This is particularly useful when routing an entire subnet (e.g., 172.16.220.0/24) through the Tillered Entry Node but requiring certain hosts within that subnet to bypass it and use the default main routing table instead.

There are two main scenarios for exclusion:

  1. Excluding Traffic to Specific Destinations: Ensures that traffic from a host follows the main routing table when communicating with certain networks.

  2. Excluding Specific Source Hosts: Allows specific devices to bypass the Tillered Entry Node entirely and use the main routing table for all traffic.

To implement these exclusions, use the following rules:

sh
# Exclude traffic from a source IP to a specific destination network
ip rule add from <source_ip> to <destination_network> lookup main priority 1000

# Exclude a specific source IP from using policy-based routing entirely
ip rule add from <excluded_source_ip> lookup main priority 1000

Example:

sh
# Ensure traffic from 172.16.220.10 to 172.16.0.0/12 follows the main routing table
ip rule add from 172.16.220.10 to 172.16.0.0/12 lookup main priority 1000

# Ensure all traffic from 172.16.220.10 does not use policy-based routing at all
ip rule add from 172.16.220.10 lookup main priority 1000

The first rule ensures that when 172.16.220.10 communicates with any destination in the 172.16.0.0/12 subnet, it follows the main routing table instead of being routed through the Tillered Entry Node. The second rule completely removes 172.16.220.10 from policy-based routing, making it behave as if no custom routes exist for it.

Step 6: Verify the Configuration ​

After applying the routing and IP rules, it is essential to confirm that traffic is correctly routed through the Tillered Entry Node.

1. Validate the Routing Table ​

Check that the custom routing table includes the expected route to the Tillered Entry Node. Run the following command to display the contents of the routing table:

sh
ip route show table vlan220_table

If configured correctly, the output should indicate that traffic is routed via the Tillered Entry Node interface:

root@unifi-device:~# ip route show table vlan220_table
default via 172.16.110.42 dev br110

If the route is missing or incorrect, recheck the configuration steps and ensure the appropriate interface and IP settings were used.

2. Verify the IP Rule ​

Confirm that the correct IP rule has been applied by listing all IP rules and filtering for the custom routing table:

sh
ip rule show | grep vlan220

A properly applied rule should produce output similar to the following:

root@unifi-device:~# ip rule show | grep vlan220
31995:  from 172.16.220.10 lookup vlan220_table

If the rule is missing, reapply the rule using Step 4 and verify again. Ensuring these configurations are in place guarantees that traffic is properly directed through the Tillered Entry Node.

Conclusion ​

This configuration ensures that traffic from 172.16.220.10 (VLAN220) is directed through the Tillered Exit Node at 172.16.110.42 (VLAN110) using policy-based routing. By implementing a custom routing table and IP rule, administrators gain enhanced control over network traffic distribution, optimizing both security and performance.

Although this guide has been tested on the UDM-Pro, the configuration methodology applies to all UniFi gateway and router solutions supporting advanced routing.