bluetooth-agent

bluetooth-agent [-h] [-i] [-c capability] [-t timeout] [-p path] [capability]

-h, --help
    Display help message and exit

-i, --insecure
    Use insecure mode; skip remote device verification

-c, --capability=CAP
    Set agent IO capability (DisplayYesNo, DisplayOnly, KeyboardDisplay, KeyboardOnly, NoInputNoOutput; default DisplayYesNo)

-t, --timeout=SEC
    Set timeout in seconds for pairing requests (default 30)

-p, --path=PATH
    Register agent for specific D-Bus service path

capability
    Positional argument for IO capability (alternative to -c)

The bluetooth-agent command is a lightweight utility from the BlueZ Linux Bluetooth protocol stack. It registers an agent handler with the Bluetooth daemon (bluetoothd) to manage incoming pairing and authentication requests from remote devices. When a device attempts to pair, the agent prompts the user via standard input/output for responses like PIN codes, passkeys, or confirmations, based on the configured IO capability.

This tool supports Bluetooth's Simple Secure Pairing (SSP) and legacy pairing modes. Common use cases include headless systems, scripts for automated pairing, or interactive sessions. It runs in the foreground by default but can be daemonized with &. The agent capability defines interaction levels: NoInputNoOutput for auto-pairing, DisplayOnly for confirmation displays, up to KeyboardDisplay for full input/output.

Capabilities align with Bluetooth specifications (Core Spec 2.0+). On startup, it announces availability via D-Bus. Timeouts prevent hanging requests. In modern setups, it's often paired with bluetoothctl for adapter management. Note that user input must be provided promptly, or pairing fails. Primarily for developers and advanced users customizing Bluetooth behavior.

(Word count: 218)

Deprecated in BlueZ 5.50+ for most uses; prefer bluetoothctl agent or client apps. Requires root or bluetooth group for D-Bus access. Interactive prompts block on stdin; unsuitable for non-interactive environments without scripting.

bluetooth-agent KeyboardDisplay &
Registers keyboard-capable agent in background.

bluetooth-agent -i NoInputNoOutput
Insecure auto-pairing mode.

NoInputNoOutput: Auto-accept.
DisplayOnly: Show passkey.
DisplayYesNo: Confirm pairing.
KeyboardOnly: Enter PIN.
KeyboardDisplay: Full interaction.

Introduced in BlueZ 4.x (circa 2008) for simple SSP handling. Evolved with Bluetooth 2.1+ specs in BlueZ 5.x. Maintained by Linux Bluetooth project; usage declined post-2017 with integrated agents in bluetoothctl.

bluetoothd(8), bluetoothctl(1), hciconfig(8), rfkill(8)