bluetooth-agent

bluetooth-agent [CAPABILITY]

CAPABILITY
    Specifies the input/output capabilities of the agent. This determines how the agent will handle PINs, passkeys, and confirmations for pairing.

DisplayOnly
    The agent can only display a PIN code or passkey, but cannot accept input from the user.

DisplayYesNo
    The agent can display a PIN code or passkey and accept a 'yes' or 'no' confirmation from the user.

KeyboardOnly
    The agent can only accept a PIN code or passkey as input from the user, but cannot display anything.

NoInputNoOutput
    The agent neither displays nor accepts input. This capability is typically used for automatic pairing where no user interaction is required (e.g., certain secure or embedded devices).

KeyboardDisplay
    The agent can both display a PIN code or passkey and accept input from the user.

The bluetooth-agent command provides a mechanism for handling various Bluetooth pairing and authentication requests generated by the BlueZ daemon (bluetoothd). It acts as an intermediary, presenting information (like PIN codes or passkeys) to the user or accepting input (like confirmations or passkeys) from the user, facilitating the secure connection process between Bluetooth devices.

Typically, an agent is required when devices need to exchange security keys or confirm pairing. Without an active agent registered with bluetoothd, pairing processes that require user interaction will fail. The bluetooth-agent can be run in different modes (capabilities) depending on the input/output capabilities of the device it represents or the user interface it interacts with. While not a primary user-facing tool for initiating connections, it is an essential background component for completing interactive Bluetooth pairings.

The exact implementation and availability of a direct bluetooth-agent command can vary across Linux distributions. It often refers to an example agent script (such as simple-agent) provided by the BlueZ project, which might be located in a non-standard PATH (e.g., /usr/lib/bluez/examples/simple-agent). It requires the bluetoothd daemon to be running and typically needs appropriate permissions (often root or membership in the 'bluetooth' group) to interact with the D-Bus system. It usually runs in the foreground until terminated or unregistered, handling incoming requests.

Users commonly interact with the agent functionality through the bluetoothctl command-line tool. After starting bluetooth-agent in a separate terminal with the desired capability, one can register it with bluetoothctl using commands like agent on and default-agent. This tells bluetoothctl and subsequently bluetoothd to use the running agent for handling authentication requests, ensuring that pairing prompts are properly managed.

bluetooth-agent is intrinsically linked to the BlueZ project, which serves as the official Linux Bluetooth protocol stack. As Bluetooth technology evolved with new security features (e.g., Secure Simple Pairing in Bluetooth 2.1), the agent functionality became crucial for handling these more complex pairing methods that require user interaction. Its development has paralleled the continuous improvements and adherence to Bluetooth specifications within the BlueZ stack.

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