---

OpenThread Border Router (OTBR) Docker

This repository provides a lightweight OpenThread Border Router (OTBR) setup, with the REST API enabled. Built from source using openthread/ot-br-posix, this image is designed for ease of use in Home Assistant.

Key Features

🪶 Lightweight Image:

Image size is approximately 118 MB, making it efficient for deployment on resource-constrained devices.

🤖 REST API Enabled:

Includes the REST API with a user-defined port.

🌐 Web UI Enabled:

Enabled with a user-defined port.

🛠️ Multiarch:

Built for amd64 and arm64 architectures.

🔒 Enhanced Firewall:

Adds bidirectional traffic filtering, allowing secure Thread and LAN communication while restricting unauthorized access.

Convenient Environment Variables:

$\hspace{15pt}$NETWORK_DEVICE: Not tested.
$\hspace{15pt}$DEVICE: Serial device (e.g., /dev/ttyUSB0).
$\hspace{15pt}$BAUDRATE: Serial baud rate (e.g., 460800).
$\hspace{15pt}$FLOW_CONTROL: Hardware flow control (e.g., 1 for enabled, 0 for disabled).
$\hspace{15pt}$BACKBONE_NET: Infrastructure interface (e.g., eth0).
$\hspace{15pt}$THREAD_NET: Thread interface (e.g., wpan0).
$\hspace{15pt}$WEB_PORT: User-defined Web UI port (default 8080).
$\hspace{15pt}$REST_PORT: User-defined REST API port (default 8081).
$\hspace{15pt}$LOG_LEVEL: OTBR log level (EMERG:0 ALERT:1 CRIT:2 ERR:3 WARN:4 NOTICE:5 INFO:6 DEBUG:7).
$\hspace{15pt}$FIREWALL: Enable or disable OTBR Firewall rules (e.g., 1 enabled (default), 0 disabled).
$\hspace{15pt}$NAT64: Enable or disable NAT64 rules (e.g., 1 enabled (default), 0 disabled).

* NAT64 disabled due to the removal of the DNS64 feature in ot-br-posix (commit f8aa002f905fc5890d3a6aa0802e2fda6bf18f4b) and a build system dependency that forces OTBR_NAT64_BORDER_ROUTING=ON when OTBR_NAT64=ON, preventing independent control of NAT64 border routing.

What's Next

Coming Soon:

• User-defined REST API port.
• Web UI enabled with user-defined port.
• Environment variables to enable/disable the Firewall and NAT64.
• ???

System Configuration

---

⚠️ IMPORTANT NOTE ⚠️

🟠 The ip6table_filter module is required for the OTBR firewall to function.
🟠 Sysctl settings required for Thread to operate correctly, enabling IPv6, forwarding, and proper RA handling.

---

Load the ip6table_filter module and ensure it persists across reboots:

sudo modprobe ip6table_filter
echo "ip6table_filter" | sudo tee -a /etc/modules-load.d/ip6table_filter.conf

Add the following to enable IPv6, forwarding, and router advertisements on the host for the Thread network:

echo "net.ipv6.conf.all.disable_ipv6 = 0" | sudo tee -a /etc/sysctl.conf
echo "net.ipv4.conf.all.forwarding = 1" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.all.forwarding = 1" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.all.accept_ra_rt_info_max_plen = 64" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.all.accept_ra = 2" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Docker Compose

services:
  otbr:
    image: ghcr.io/d34dc3n73r/otbr-docker
    container_name: otbr
    network_mode: host
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
      - NET_ADMIN
      - NET_RAW
    volumes:
      - ./otbr:/data/thread # Thread network persistent data storage
      - /etc/localtime:/etc/localtime:ro
    environment:
      NETWORK_DEVICE: # Network Device (Leave empty, remove, or comment out if not used)
      DEVICE: /dev/ttyUSB0 # RCP Device Path
      BAUDRATE: 460800 # RCP Baudrate
      FLOW_CONTROL: 1 # Hardware Flow Control
      BACKBONE_NET: eth0 # Main Network Interface
      THREAD_NET: wpan0 # Thread Network Interface
      WEB_PORT: 8080 # User-defined Web UI port
      REST_PORT: 8081 # User Defined REST API PORT
      LOG_LEVEL: 3 # emergency=0 alert=1 critical=2 error=3 warning=4 notice=5 info=6 debug=7
      FIREWALL: 1 # Enable OTBR Enhanced Firewall
      # NAT64 disabled due to the removal of the DNS64 feature in ot-br-posix
      # (commit f8aa002f905fc5890d3a6aa0802e2fda6bf18f4b) and a build system dependency
      # that forces OTBR_NAT64_BORDER_ROUTING=ON when OTBR_NAT64=ON, preventing
      # independent control of NAT64 border routing.
      #NAT64: 0 # Enable NAT64 rules
    devices:
      - /dev/ttyUSB0
      - /dev/net/tun

Auto release triggered by openthread/border-router

• This repository auto releases a multiarch image which is triggered by openthread/border-router image releases so it's always up to date. Works best with recent RCP firmware.