---

OpenThread Border Router (OTBR) Docker

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

Key Features

🪶 Lightweight Image:

Multi-stage build produces a small image, making it efficient for deployment on resource-constrained devices.

🤖 REST API Enabled:

Includes the REST API with a user-defined port, listening on all interfaces for Docker compatibility.

🌐 Web UI Enabled:

Enabled with a user-defined port.

🛠️ Multiarch:

Built for amd64 and arm64 architectures.

🔒 Enhanced Firewall:

Adds bidirectional traffic filtering with dynamic LAN IPv6 prefix detection, allowing secure Thread and LAN communication while restricting unauthorized access. Can be toggled on/off at runtime.

🌍 NAT64 Translation:

Built-in NAT64 support using upstream's CIDR-based translator (192.168.255.0/24), allowing Thread devices to reach IPv4-only services. Can be toggled on/off at runtime.

🔧 OpenThread mDNS:

Uses OpenThread's built-in mDNS implementation with DNS-SD Discovery Proxy and SRP Advertising Proxy — no external mDNS daemon required.

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 Enhanced Firewall (e.g., 1 enabled (default), 0 disabled).
$\hspace{15pt}$NAT64: Enable or disable NAT64 translation rules (e.g., 1 enabled (default), 0 disabled).

Upstream OT_* environment variables (e.g., OT_RCP_DEVICE, OT_INFRA_IF, OT_THREAD_IF) are also supported as fallbacks.

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.
• NAT64 re-enabled with upstream's CIDR-based translator.
• Switched to OpenThread built-in mDNS (no more mDNSResponder).
• ???

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: 1 # Enable NAT64 translation
    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.