Sign inSign up

thehecateii/docker-bbox

By thehecateii

•Updated 4 months ago

A Docker image that transforms your host into a Bouygues Telecom BBox

Buildkit cache
Image
Networking
0

261

thehecateii/docker-bbox repository overview

A Docker image that transforms your host into a Bouygues Telecom BBox, allowing you to bypass the BBox router and use your own hardware with Bouygues fiber (FTTH) in France.

⁠What it does

  • Creates a VLAN 100 interface on the WAN interface
  • Applies CoS 6 priority to DHCP traffic (required for stable IP assignment)
  • Sends DHCP Option 60 BYGTELIAD and optionally Option 125 (device fingerprint)
  • Optionally clones the BBox MAC address
  • Obtains an IPv4 address and IPv6 prefix delegation (/60)
  • Sets up NAT and forwarding between LAN and WAN

⁠Hardware compatibility

A kernel bug was previously affecting nftables netdev egress hooks on VLAN interfaces with certain network drivers, causing the DHCP wildcard address to shift from 0.0.0.0 to 0.0.255.255, which Bouygues rejects.

This issue is now fully resolved through an eBPF TC egress program that intercepts outgoing DHCP packets and corrects the corrupted source address before transmission. This fix has been thoroughly tested across all environments and is the official, stable solution included in the image.

You can run this image reliably on:

  • ✅ Virtualized environments (Proxmox, QEMU, KVM with VirtIO)
  • ✅ Raspberry Pi 4 and 5
  • ✅ Bare metal with any network driver
  • ✅ Any other supported Linux environment with Docker

⁠Limitations

  • TV not supported — Bouygues TV requires IGMP Proxy configuration which is not handled by this container
  • VoIP not supported — Bouygues does not provide SIP credentials to third-party equipment

⁠Requirements

  • A Linux host with Docker installed
  • Two network interfaces (LAN and WAN connected to the ONT)
  • The MAC address of your BBox (recommended)
  • --privileged mode and --network host

⁠Usage

⚠️ WARNING: Before starting, please ensure that the IP Full-Stack option is enabled in your customer portal. If it is not, your connection will use MAP-T or CGNAT, which will prevent this standard DHCP configuration from working properly.

docker run -d \
  --name bbox \
  --privileged \
  --network host \
  -e BBOX_MAC=xx:xx:xx:xx:xx:xx \
  -e LAN_INTERFACE=eth0 \
  -e WAN_INTERFACE=eth1 \
  -e LAN_SUBNET=192.168.1.0/24 \
  thehecateii/docker-bbox:latest

⁠Environment Variables

VariableDefaultDescription
BBOX_MAC(empty)WAN MAC address of your BBox (label on the back)
LAN_INTERFACEeth0LAN-side network interface
WAN_INTERFACEeth1WAN-side network interface (connected to the ONT)
LAN_SUBNET192.168.1.0/24LAN subnet for NAT masquerading
MTU1500MTU for the VLAN interface
BBOX_DEVICE_ID(empty)Option 125 sub-option 1 (e.g. 001BBF)
BBOX_SERIAL(empty)Option 125 sub-option 2 (e.g. 124235801379499)
BBOX_HW_VERSION(empty)Option 125 sub-option 3 (e.g. 5330b-r1)

BBOX_DEVICE_ID, BBOX_SERIAL and BBOX_HW_VERSION are all required together to include Option 125. If any is missing, Option 125 is omitted. These values can be found by capturing the BBox DHCP traffic before replacing it.

⁠Source & Documentation

Full source code and documentation available on GitHub⁠.

Tag summary

Content type

Image

Digest

sha256:da02e4b19…

Size

120.3 MB

Last updated

4 months ago

docker pull thehecateii/docker-bbox