fips/docs/how-to/set-up-bluetooth-peer.md

Set Up a Bluetooth (BLE) Peer Link

FIPS supports Bluetooth Low Energy as a transport for short-range mesh extension — same room, same building, no IP infrastructure between the two endpoints. The BLE transport runs as L2CAP Connection-Oriented Channels on a configurable PSM and reports per-link MTU back to the mesh layer for path-MTU computation.

For the design rationale and per-link MTU model, see ../design/fips-transport-layer.md. For all transports.ble.* configuration keys, see ../reference/configuration.md.

Experimental. The BLE transport works but is still maturing. Expect rougher edges than UDP or TCP — particularly around link stability under interference and MTU negotiation on older controllers. Treat it as you would any experimental transport in a production deployment.

When to use

BLE is the right transport when:

• Two nodes are within roughly 10 metres line-of-sight (more with external antennas, less through walls).
• You want a self-contained mesh segment with no shared WiFi or Ethernet between the participants.
• You can work within practical L2CAP CoC throughput (1-2 Mbps in good conditions, often substantially less under interference or at range) and the higher latency variance compared to WiFi.

It is not the right transport for backbone links between rooms where WiFi or Ethernet exists, for high-throughput data, or for any deployment where range matters more than infrastructure-freedom.

Platform support

The BLE transport is Linux-only in the current implementation. The runtime depends on BlueZ via the bluer crate, which in turn needs glibc (musl builds skip BLE; the build script gates the crate accordingly).

Platform	BLE transport
Linux (glibc)	Supported.
Linux (musl, OpenWrt)	Disabled at build time.
Android	Supported (native Android BLE, via the embedder's radio bridge).
macOS	Not supported.
Windows	Not supported.

The Debian package Recommends: bluez; install it explicitly if you opted out:

sudo apt install bluez

Prerequisites

Both endpoints need:

1. A BLE-capable HCI adapter visible to BlueZ. Confirm with:

   sudo bluetoothctl show
   

   Note the controller name (typically hci0).

2. The bluetoothd service running and the adapter powered on:

   sudo systemctl enable --now bluetooth
   sudo bluetoothctl power on
   

3. Sufficient privileges for the FIPS daemon. There are two independent privilege concerns; the BLE-only deployment case (mesh router with tun.enabled: false) needs only the second.

   • TUN adapter (always required when tun.enabled: true). The daemon needs CAP_NET_ADMIN to create and configure the TUN device. The shipped systemd unit handles this by running as root; if you prefer to drop privileges, see run-as-unprivileged-user.md.

   • BLE access (required for this how-to). BlueZ exposes L2CAP and D-Bus paths under either group membership or CAP_NET_RAW. Pick one:

     • Run the daemon as root. The shipped systemd unit takes this route.

     • Run as an unprivileged user that is a member of the bluetooth group. No additional capability is needed for the BLE side.

     • Run as an unprivileged user with no group membership, and grant the binary CAP_NET_RAW:

       sudo setcap cap_net_raw+ep $(which fips)
       

       This bypasses BlueZ's polkit/group check by holding CAP_NET_RAW directly. If you also need CAP_NET_ADMIN for TUN, combine them:

       sudo setcap cap_net_admin,cap_net_raw+ep $(which fips)
       

4. The same L2CAP PSM on both endpoints. The default is 0x0085 (133); override only if you need to coexist with another L2CAP service on that PSM.

Configuration

Add a ble block under transports in fips.yaml. A minimum BLE- active node looks like this:

transports:
  ble:
    adapter: "hci0"
    advertise: true
    scan: true
    auto_connect: true
    accept_connections: true

Note: auto_connect: true is intentionally non-default (the default is false). For a symmetric ground-up discovery flow where either side may dial, both ends must opt in explicitly.

Key	Purpose
adapter	HCI controller name. Default: hci0.
psm	L2CAP PSM. Default: 0x0085 (must match on both ends).
mtu	Default L2CAP CoC MTU. Default: 2048. The kernel may negotiate lower per link.
max_connections	Concurrent BLE connections. Default: 7 (Bluetooth controllers typically support up to ~7 simultaneous L2CAP CoCs).
advertise	Broadcast our BLE adverts so other FIPS nodes discover us. Default: true.
scan	Listen for other FIPS nodes' BLE adverts. Default: true.
auto_connect	Initiate a BLE connection to discovered FIPS adverts. Default: false.
accept_connections	Accept inbound L2CAP connections. Default: true.
connect_timeout_ms	Outbound L2CAP connect timeout. Default: 10000.
probe_cooldown_secs	After probing a BD_ADDR (success or failure), wait this long before probing it again. Default: 30.

Two pairing patterns are common:

Symmetric auto-discovery. Both nodes advertise, scan, and auto-connect. Whichever side completes the L2CAP connection first wins; the other side aborts its in-flight attempt. This is the "toss two devices in the same room" setup.

# Both nodes
transports:
  ble:
    adapter: "hci0"
    advertise: true
    scan: true
    auto_connect: true
    accept_connections: true

Asymmetric peripheral / central. One node only listens (peripheral), the other actively dials (central). Useful when one endpoint is a dedicated bootstrap and the other is mobile.

# Listener
transports:
  ble:
    adapter: "hci0"
    advertise: true
    scan: false
    auto_connect: false
    accept_connections: true

# Dialer
transports:
  ble:
    adapter: "hci0"
    advertise: false
    scan: true
    auto_connect: true
    accept_connections: false

After editing, restart the daemon on each side:

sudo systemctl restart fips

Verify

On each endpoint, confirm the transport came up:

fipsctl show transports

Look for an entry of type ble in the state: Running (or equivalent) state. The mtu field reports the configured default; per-link MTU is reported separately.

Confirm the link is established:

fipsctl show peers

The peer entry for the BLE-attached neighbour should report transport_type: "ble" and a non-zero last_seen_ms.

BLE peering is auto-discovery only: there is no fipsctl connect path for BLE (the command accepts udp, tcp, tor, and ethernet only). Links come up via advert/scan; if you don't see the peer here, the configuration above is the only knob.

To watch the link in real time, use fipstop's Peers and Transports tabs:

fipstop

The Performance tab reports the per-link MMP metrics — SRTT, loss rate, ETX — which on BLE typically run an order of magnitude worse than over UDP, with much higher jitter.

Troubleshooting

Transport never comes up

Check the BlueZ side first:

systemctl status bluetooth
sudo bluetoothctl show

If bluetoothctl show reports Powered: no, fix that before debugging FIPS. The FIPS daemon will log a warning if it cannot acquire the adapter.

If the FIPS log contains bluer D-Bus errors, the daemon usually lacks permission. Run as root or grant CAP_NET_ADMIN and add the fips user to the bluetooth group.

Peers see each other but never connect

Verify accept_connections is true on at least one side and auto_connect is true on at least one side. Two listen-only nodes will discover each other but never establish an L2CAP connection.

Check psm matches on both ends. A mismatch presents as adverts visible (in fipstop discovery counters) but every connect attempt fails.

Link comes up but throughput is poor

Practical L2CAP CoC throughput in good conditions reaches 1-2 Mbps, but interference, range, and controller capability all push it lower. If throughput is well below that range, check the negotiated ATT_MTU — a small ATT_MTU (default 23 bytes when extended ATT MTU is not negotiated) caps per-PDU payload regardless of radio conditions. The per-link MTU reported in fipsctl show transports reveals what was negotiated.

If MTU is unexpectedly low, both endpoints must support and have negotiated the BlueZ L2CAP cocmode=2 extension. Older Bluetooth controllers cap MTU regardless.

Unstable links / repeated reconnects

Bluetooth in busy 2.4 GHz environments suffers from WiFi interference. Switch the adapter to a less crowded channel (kernel side, not configurable from FIPS) or add an external antenna. The probe_cooldown_secs tunable backs off retry attempts; raise it if the daemon log shows many short-lived probes.

Permission errors on socket open

Most modern systemd installs do not allow non-root processes to open raw L2CAP sockets without an explicit policy. Run the daemon as root (the shipped systemd unit does this) or add a polkit rule for the bluetooth group.

See also

• ../design/fips-transport-layer.md — per-transport MTU reporting and the BLE row of the supported- transports table.
• ../reference/configuration.md — full transports.ble.* reference.
• run-as-unprivileged-user.md — adjacent privilege handling for the daemon process.