OTBR + Matter Server con SLZB-06 su Proxmox

1 Introduzione

Questa guida spiega come configurare un'antenna Thread (OpenThread Border Router) con Matter Server in LXC su Proxmox VE, usando gli helper-scripts della community (community-scripts.org). Perfetto per chi vuole portare in Home Assistant dispositivi Matter over Thread: sensori, lampadine, prese smart, ecc.

┌─────────────────────────────────────────────────────┐
│                     Proxmox VE                      │
│                                                     │
│  ┌──────────┐    ┌──────────────┐    ┌───────────┐  │
│  │  OTBR    │    │ Matter Server│    │  Home     │  │
│  │  (LXC)   │◄──►│   (LXC)      │◄──►│ Assistant │  │
│  │10.x.x.17 │    │ 10.x.x.16    │    │  (LXC)    │  │
│  └────┬─────┘    └──────────────┘    └───────────┘  │
│       │ TCP 6638                                     │
│       ▼                                              │
│  ┌──────────┐                                        │
│  │ SLZB-06  │  (coordinator PoE)                     │
│  │10.x.x.200│                                        │
│  └──────────┘                                        │
└─────────────────────────────────────────────────────┘

• SLZB-06: coordinator PoE collegato via Ethernet, agisce da RCP (Radio Co-Processor)
• OTBR (OpenThread Border Router): collega la rete Thread alla LAN e all'IPv6
• Matter Server: espone le API per far comunicare Home Assistant con i dispositivi Matter
• Home Assistant: interfaccia utente finale, con integrazioni OTBR + Matter

2 Prerequisiti

3 Configurazione iniziale SLZB-06

3.1 Assegnare IP statico

Accedi al WebUI dello SLZB-06 (http://slzb-06.local o dall'IP ricevuto via DHCP) e configura un IP statico per evitare che cambi dopo un riavvio del router:

• IP: 192.168.1.200 (adatta alla tua subnet)
• Subnet: 255.255.255.0
• Gateway: 192.168.1.1
• DNS: 1.1.1.1

3.2 Verificare la porta TCP

OTBR si connette allo SLZB-06 via TCP sulla porta 6638. Verifica la raggiungibilità dal Proxmox host prima di procedere:

echo > /dev/tcp/192.168.1.200/6638 && echo "OK" || echo "FAIL"

4 Creazione LXC OTBR

4.1 Eseguire l'helper-script

Sul Proxmox host, esegui:

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/create_lxc.sh)"

Cerca "otbr" o "OpenThread Border Router" e segui la procedura guidata. Durante la creazione assicurati di:

• Assegnare un IP statico (es. 192.168.1.17/24)
• Inserire il gateway corretto
• Abilitare l'avvio automatico (onboot)

4.2 Configurazione IP post-creazione

Se non hai impostato l'IP durante la creazione, modificalo da Proxmox:

pct set 109 --net0 name=eth0,bridge=vmbr0,ip=192.168.1.17/24,gw=192.168.1.1

Oppure modifica direttamente /etc/network/interfaces dentro l'LXC:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
    address 192.168.1.17/24
    gateway 192.168.1.1

E configura i DNS:

echo -e "nameserver 1.1.1.1\nnameserver 1.0.0.1" > /etc/resolv.conf

5 Modifiche critiche all'LXC OTBR

5.1 TUN/TAP device

OTBR ha bisogno del device /dev/net/tun per creare l'interfaccia Thread (wpan0). Senza questo mount il servizio non parte.

Arresta l'LXC, poi aggiungi queste righe al file /etc/pve/lxc/109.conf (sostituisci 109 con il tuo VMID):

lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

• c 10:200 rwm — autorizza il device /dev/net/tun (major 10, minor 200) con permessi r/w
• lxc.mount.entry — monta il device dal host dentro il container via bind mount

In alternativa, usa pct set:

pct set 109 -lxc.cgroup2.devices.allow "c 10:200 rwm"
pct set 109 -lxc.mount.entry "/dev/net/tun dev/net/tun none bind,create=file"

5.2 Verificare il mount

Riavvia l'LXC e controlla che il device sia presente:

pct start 109
pct exec 109 -- ls -la /dev/net/tun

crw------- 1 root root 10, 200 ... /dev/net/tun

6 Configurazione OTBR Agent

6.1 Modificare il file di configurazione

Il cuore della configurazione è /etc/default/otbr-agent dentro l'LXC OTBR. Per SLZB-06 (connessione via rete TCP):

OTBR_AGENT_OPTS="-I wpan0 -B eth0 \
  --vendor-name OpenThread --model-name BorderRouter \
  --rest-listen-address 0.0.0.0 --rest-listen-port 8081 \
  spinel+hdlc+forkpty:///usr/bin/socat?forkpty-arg=-,rawer&forkpty-arg=tcp:192.168.1.200:6638 \
  trel://eth0"

Parametri spiegati:

• -I wpan0 — nome dell'interfaccia Thread
• -B eth0 — interfaccia di backbone (LAN)
• --rest-listen-address 0.0.0.0 --rest-listen-port 8081 — REST API usata da Matter Server
• spinel+hdlc+forkpty:///usr/bin/socat...tcp:192.168.1.200:6638 — usa socat come bridge tra TCP (SLZB-06) e pseudo-terminal (OTBR parla con un RCP via protocollo seriale)
• trel://eth0 — abilita Thread Radio Encapsulation Link (migliora la comunicazione tra più border router)

6.2 Riavviare il servizio

pct exec 109 -- systemctl restart otbr-agent
pct exec 109 -- systemctl enable otbr-agent

6.3 Abilitare IPv6 forwarding

OTBR abilita automaticamente net.ipv6.conf.all.forwarding = 1 all'avvio. Verificalo:

pct exec 109 -- sysctl net.ipv6.conf.all.forwarding
# Atteso: net.ipv6.conf.all.forwarding = 1

Se non fosse attivo, aggiungilo in modo persistente:

net.ipv6.conf.all.forwarding = 1
net.ipv6.conf.default.forwarding = 1

7 Verifica OTBR funzionante

7.1 Interfaccia Thread

pct exec 109 -- ip link show wpan0

wpan0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> ...

7.2 Stato del servizio

pct exec 109 -- systemctl status otbr-agent

Deve mostrare active (running).

7.3 WebUI OTBR

# Da terminale
pct exec 109 -- curl -s http://127.0.0.1
# Dal browser: http://192.168.1.17

7.4 Verifica connettività SLZB-06

pct exec 109 -- bash -c 'echo > /dev/tcp/192.168.1.200/6638 && echo "OK" || echo "FAIL"'

8 Creazione LXC Matter Server

8.1 Eseguire l'helper-script

bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/create_lxc.sh)"

Cerca "matter-server" e segui la procedura, assegnando un IP statico sulla stessa rete (es. 192.168.1.16/24).

8.2 Verificare il servizio

pct exec 108 -- systemctl status matter-server

Deve mostrare active (running).

8.3 WebUI Matter Server

Matter Server espone una WebUI sulla porta 5580:

pct exec 108 -- curl -s http://127.0.0.1:5580
# Dal browser: http://192.168.1.16:5580

9 Firewall Proxmox

9.1 Il problema

Proxmox VE imposta la policy FORWARD di iptables su DROP per default. Questo blocca il traffico tra i vari LXC anche se sono sulla stessa bridge (vmbr0).

iptables -L FORWARD -n
# Chain FORWARD (policy DROP)  ← PROBLEMA!

9.2 La soluzione

Aggiungi regole per accettare il forwarding sulla bridge principale:

iptables -I FORWARD 1 -i vmbr0 -j ACCEPT
iptables -I FORWARD 1 -o vmbr0 -j ACCEPT

Per renderle permanenti dopo il riavvio:

apt-get install -y iptables-persistent
netfilter-persistent save

10 Integrazione in Home Assistant

10.1 Aggiungere OTBR

1. In HA vai su Impostazioni → Dispositivi e servizi → Aggiungi integrazione
2. Cerca "OpenThread Border Router"
3. Inserisci l'IP dell'LXC OTBR (es. 192.168.1.17) e la porta REST API (default: 8081)
4. HA scoprirà automaticamente il border router

10.2 Aggiungere Matter

1. Vai su Impostazioni → Dispositivi e servizi → Aggiungi integrazione
2. Cerca "Matter"
3. Inserisci l'IP dell'LXC Matter Server (es. 192.168.1.16)
4. Segui la procedura di commissioning

10.3 Commissionare un dispositivo

Per aggiungere un dispositivo Matter over Thread:

1. Metti il dispositivo in pairing mode (di solito reset o pressione lunga)
2. In HA: Aggiungi dispositivo → Matter → Commissiona con codice
3. Inserisci il codice di commissioning (QR code o manual code fornito col dispositivo)

11 Troubleshooting

● otbr-agent.service - Main process exited, code=exited, status=1/FAILURE

bash: connect: Connection refused
bash: /dev/tcp/192.168.1.200/6638: Connection refused

journalctl -u otbr-agent -f
...
[ERROR] Failed to connect to RCP: Connection refused

pct exec 108 -- curl -s http://192.168.1.17:8081

pct exec 109 -- sysctl net.ipv6.conf.all.forwarding
# Deve essere = 1

pct exec 109 -- ip -6 addr show eth0
# Deve mostrare almeno un indirizzo IPv6 link-local (fe80::...)