boltctl

List connected (and authorized) devices

$ boltctl

$ boltctl list

$ boltctl authorize [device_uuid]

$ boltctl enroll [device_uuid]

$ boltctl forget [device_uuid]

$ boltctl info [device_uuid]

boltctl [OPTIONS] COMMAND [ARGUMENTS]

-V, --version
    Display the version information of the boltctl utility and exit.

-h, --help
    Show a help message describing command usage and available options, then exit.

list, devices
    List all detected Thunderbolt controllers and connected devices, providing a summary of their status and properties.

info UUID
    Show detailed information about a specific Thunderbolt device, identified by its unique ID (UUID).

enroll UUID
    Enroll a new Thunderbolt device, typically a prerequisite step before authorization for certain security policies.

authorize UUID
    Authorize a Thunderbolt device identified by its UUID. Once authorized, the device is fully functional and trusted.

forget UUID
    Remove a Thunderbolt device from the list of enrolled or authorized devices, revoking its access and preventing future automatic connection.

domain [COMMAND] [UUID]
    Manage Thunderbolt domains. Use 'boltctl domain help' for available subcommands like 'list', 'info', or 'power'.

power STATE
    Control the power state of Thunderbolt controllers. STATE can be 'on' to enable or 'off' to disable.

monitor
    Monitor Thunderbolt events in real-time, such as device connection, disconnection, or authorization changes.

config
    Manage and inspect the configuration of the boltd daemon.

The boltctl command-line utility provides comprehensive management for Thunderbolt 3 (and newer compatible) devices connected to a Linux system. It serves as the primary interface to the boltd daemon, which is responsible for handling Thunderbolt security, device enumeration, and authorization policies. Users can leverage boltctl to list all connected Thunderbolt controllers and peripherals, retrieve detailed information about specific devices using their unique identifiers (UUIDs), and critically, manage their authorization status.

Given that Thunderbolt devices possess Direct Memory Access (DMA) capabilities, authorization is a paramount security feature, preventing unauthorized access to system memory. boltctl facilitates this by allowing users to enroll new devices, explicitly authorize them for full functionality, or forget previously authorized ones to revoke access, thereby ensuring system integrity and preventing potential security exploits.

Permissions: Most boltctl commands that modify device status (e.g., authorize, forget) require root privileges or membership in a specific administrative group (e.g., 'plugdev').

Daemon Requirement: The boltd service must be actively running in the background for boltctl to communicate with Thunderbolt hardware and manage devices.

Kernel Support: Proper kernel support for Thunderbolt technology is essential for device detection and management; without it, boltctl will not function.

Thunderbolt Version: While it may show some information for older versions, boltctl and boltd are primarily designed for Thunderbolt 3 and newer compatible versions, which implement the security model requiring explicit device authorization.

Thunderbolt's ability for Direct Memory Access (DMA) means a malicious device could potentially read or write directly to system memory, bypassing operating system security. boltctl's authorization mechanism is vital to mitigate this. By requiring explicit user approval for devices, it protects against 'Evil Maid' attacks and ensures only trusted peripherals can interact with the system's memory.

A typical scenario for connecting a new Thunderbolt device might involve these steps:
1. Connect the Thunderbolt device to your system.
2. Run `boltctl list` to identify the new device (it may show as 'disconnected' or 'unauthorized').
3. Note the device's UUID.
4. Execute `sudo boltctl authorize UUID` to grant the device full access to the system.
5. The device should now be recognized and fully functional within your Linux environment.

The boltctl command emerged as a crucial component of the boltd project, developed to provide a standardized, secure, and robust way to manage Thunderbolt devices on Linux. With the advent of Thunderbolt 3, which introduced advanced security features like DMA protection and mandatory device authorization, a dedicated userspace daemon and its accompanying command-line interface became indispensable. Before boltd and boltctl, Thunderbolt management on Linux was often ad-hoc or reliant on vendor-specific drivers, lacking a unified security model. This project has significantly improved user experience and system security by offering a consistent and reliable interface for Thunderbolt device interaction across various Linux distributions.

boltd(8), lspci(8), dmesg(1), udevadm(8)