vardo/trusttunnel-client-mikrotik repository overview

⁠TrustTunnel Client for MikroTik RouterOS

This repository contains a container with TrustTunnel Client intended for execution in the container subsystem of MikroTik RouterOS version 7.20 and later.

The container implements a client connection to a TrustTunnel Endpoint and provides transmission of RouterOS IP traffic through a VPN interface created inside the container.

The container does not perform any automatic configuration of RouterOS. Routing, NAT, and firewall on the RouterOS side must be configured manually.

⁠Container purpose

The container performs the following functions:

establishes a TLS connection to the TrustTunnel Endpoint; authenticates to the Endpoint using the provided credentials; creates a VPN interface tun0 inside the container; receives IP traffic from RouterOS via a veth interface; routes the received traffic into the VPN interface tun0.

The container is used as a TrustTunnel VPN client and as a network gateway between RouterOS and the VPN tunnel.

⁠Supported RouterOS architectures

Containers are supported by RouterOS on ARM (armv7), ARM64, and x86_64 (CHR).

The image is published as a single multi-arch Docker image. RouterOS automatically pulls the image variant matching the device architecture.

⁠Required environment variables

To start the container, all of the following environment variables must be defined:

TT_ADDRESS = ip:port
TT_HOSTNAME = hostname
TT_USER = username
TT_PASS = password

⁠Purpose:

TT_ADDRESS — IP address of the TrustTunnel Endpoint with port; domain names are not used;
TT_HOSTNAME — endpoint hostname used for TLS/SNI;
TT_USER and TT_PASS — TrustTunnel credentials.

⁠Container network

The container is connected to RouterOS via a veth interface named TT-VETH.

Recommended addressing scheme:

Container IP: 172.31.31.1/30
RouterOS IP: 172.31.31.2/30

⁠RouterOS deployment commands (step by step)

⁠1. Verify that the container subsystem is available and that a disk/USB device exists for container layers:

/system/resource/print
/disk/print

Requirement: storage used for containers must be ext4 (otherwise “create failed” errors may occur during layer unpacking).

⁠2. Create directories for layers/tmp (example: usb1-part1):

/file add name=usb1-part1/ct-layers type=directory
/file add name=usb1-part1/ct-tmp type=directory

⁠3. Configure the container subsystem (Docker Hub registry):

/container/config/set layer-dir=usb1-part1/ct-layers tmpdir=usb1-part1/ct-tmp memory-high=160MiB registry-url=(https://registry-1.docker.io⁠) username=YOUR_DOCKERHUB_LOGIN The Docker Hub password is set in WinBox: Container → Config → Password (or via /container/config if supported by your RouterOS version).

⁠4. Create a veth interface for RouterOS ↔ container connectivity:

/interface/veth/add name=TT-VETH address=172.31.31.2/30 gateway=172.31.31.1
/ip/address/add interface=TT-VETH address=172.31.31.2/30

⁠5. NAT for the container network (to allow outbound access / TLS connection to the endpoint):

/ip/firewall/nat/add chain=srcnat src-address=172.31.31.0/30 action=masquerade comment="TrustTunnel CT NAT 172.31.31.0/30"

⁠6. Allow forward traffic from the container network (if forward is dropped by default):

/ip/firewall/filter/add chain=forward src-address=172.31.31.0/30 action=accept place-before=0 comment="TrustTunnel CT allow forward"

⁠7. Create the envlist (replace values with your own):

/container/envs/remove [find list=ttenv]
/container/envs/add list=ttenv key=TT_ADDRESS value=ENDPOINT_IP:443
/container/envs/add list=ttenv key=TT_HOSTNAME value=ENDPOINT_HOSTNAME
/container/envs/add list=ttenv key=TT_USER value=USERNAME
/container/envs/add list=ttenv key=TT_PASS value=PASSWORD

⁠8. Create the container (multi-arch image — the same for all supported MikroTik/CHR platforms), version 0.99.101 is specified:

/container/add name=trusttunnel-client remote-image=vardo/trusttunnel-client-mikrotik:0.99.101 interface=TT-VETH envlist=ttenv dns=8.8.8.8,1.1.1.1 logging=yes start-on-boot=yes
/container/start trusttunnel-client

⁠9. Status and log verification:

/container/print detail where name="trusttunnel-client" /log/print where message~"trusttunnel-client|VPN_SS_|CONNECTED|DISCONNECTED|endpoint|pinger"

⁠10. Mandatory requirement when routing “all traffic through VPN”:

RouterOS must have a separate direct route to the endpoint IP (to avoid attempting to reach the endpoint through the tunnel itself). The exact command depends on your WAN; a generic example:

/ip/route/add dst-address=ENDPOINT_IP/32 gateway=WAN_GATEWAY distance=1 comment="Endpoint direct (bypass VPN)"

⁠11. Routing via the container (gateway is the container IP, not the interface):

Test with a single destination:

/ip/route/add dst-address=8.8.8.8/32 gateway=172.31.31.1 distance=1 comment="TEST via TrustTunnel CT"
Default route via the container (apply after successful testing):
/ip/route/add dst-address=0.0.0.0/0 gateway=172.31.31.1 distance=2 comment="DEFAULT via TrustTunnel CT"

⁠How the container is built

The container is built from official TrustTunnel Client binary releases without recompilation and without modifying the source code:

base image: Alpine Linux 3.20 installed packages: ca-certificates, iproute2 an entrypoint.sh script is added, which generates the configuration from environment variables, starts the client, and configures policy routing inside the container (table 100, default via tun0, iif TT-VETH → lookup 100, exclusion of the endpoint IP from VPN routing)

⁠Limitations

the container is intended to run only in MikroTik RouterOS (containers subsystem);
the container does not configure NAT or firewall rules;
the container does not manage RouterOS routing;
all RouterOS routing logic must be configured outside the container.