BlueZ settings storage ********************** Purpose ======= The purpose of this document is to describe the directory structure of BlueZ settings storage. In effect, this document will serve as the primary, up to date source of BlueZ storage information. It is intended as reference for developers. Direct access to the storage outside from bluetoothd is highly discouraged. Adapter and remote device info are read form the storage during object initialization. Write to storage is performed immediately on every value change. Default storage directory is /var/lib/bluetooth. This can be adjusted by the --localstatedir configure switch. Default is --localstatedir=/var. When loading as a service the storage directory can be set via StateDirectory environment variable: https://www.freedesktop.org/software/systemd/man/systemd.exec.html All files are in ini-file format. Storage directory structure =========================== The storage root directory contains an optional addresses file that's used for managing adapters that come without a pre-allocated address. The format of the addresses file is: [Static] = Each adapter with an assigned address has its own subdirectory under the root, named based on the address, which contains: - a settings file for the local adapter - an attributes file containing attributes of supported LE services - an admin policy file containing current values of admin policies - a cache directory containing: - one file per device, named by remote device address, which contains device name - one directory per remote device, named by remote device address, which contains: - an info file - an attributes file containing attributes of remote LE services - a ccc file containing persistent Client Characteristic Configuration (CCC) descriptor information for GATT characteristics So the directory structure is: /var/lib/bluetooth// ./settings ./attributes ./admin_policy_settings ./cache/ ./ ./ ... .// ./info ./attributes ./ccc .// ./info ./attributes ... Settings file format ==================== Settings file contains one [General] group with adapter info like: Alias String Friendly user provided name advertised for this adapter This value overwrites the system name (pretty hostname) Discoverable Boolean Discoverability of the adapter PairableTimeout Integer How long to stay in pairable mode before going back to non-pairable. The value is in seconds. 0 = disable timer, i.e. stay pairable forever DiscoverableTimeout Integer How long to stay in discoverable mode before going back to non-discoverable. The value is in seconds. 0 = disable timer, i.e. stay discoverable forever Sample: [General] Name=My PC Discoverable=false Pairable=true DiscoverableTimeout=0 Identity file format ==================== Identity file contains one [General] group that holds identity information such as keys and adresses: IdentityResolvingKey String 128-bit value of the IRK Sample: [General] IdentityResolvingKey=00112233445566778899aabbccddeeff Attributes file format ====================== The attributes file lists all attributes supported by the local adapter or remote device. Attributes are stored using their handle as group name (decimal format). Each group contains: UUID String 128-bit UUID of the attribute Value String Value of the attribute as hexadecimal encoded string EndGroupHandle Integer End group handle in decimal format Sample: [1] UUID=00002800-0000-1000-8000-00805f9b34fb Value=0018 [4] UUID=00002803-0000-1000-8000-00805f9b34fb Value=020600002A [6] UUID=00002a00-0000-1000-8000-00805f9b34fb Value=4578616D706C6520446576696365 Admin Policy file format ====================== The admin policy file stores the current value of each admin policy. [General] group contains: ServiceAllowlist List of List of service UUID allowed by strings adapter in 128-bits format, separated by ','. Default is empty. Sample: [General] ServiceAllowlist= CCC file format ====================== The ccc file stores the current CCC descriptor values for GATT characteristics which have notification/indication enabled by the remote device. Information is stored using CCC attribute handle as group name (in decimal format). Each group contains: Value String CCC descriptor value encoded in hexadecimal Cache directory file format ============================ Each file, named by remote device address, may includes multiple groups (General, ServiceRecords, Attributes, Endpoints, NameResolving). In ServiceRecords, SDP records are stored using their handle as key (hexadecimal format). In "Attributes" group GATT database is stored using attribute handle as key (hexadecimal format). Value associated with this handle is serialized form of all data required to re-create given attribute. ":" is used to separate fields. In "Endpoints" group A2DP remote endpoints are stored using the seid as key (hexadecimal format) and ":" is used to separate fields. It may also contain an entry which key is set to "LastUsed" which represented the last endpoint used. In "NameResolving", information regarding remote name resolving are stored to prevent wasting time resolving name for unresponsive devices. [General] group contains: Name String Remote device friendly name ShortName String Remote device shortened name [ServiceRecords] group contains <0x...> String SDP record as hexadecimal encoded string In [Attributes] group value always starts with attribute type, that determines how to interpret rest of value: Primary service: 2800:end_handle:uuid Secondary service: 2801:end_handle:uuid Included service: 2802:start_handle:end_handle:uuid Characteristic: 2803:value_handle:properties:uuid Descriptor: value:uuid uuid Sample Attributes section: [Attributes] 0001=2800:0005:1801 0002=2803:0003:20:2a05 0014=2800:001c:1800 0015=2803:0016:02:2a00 0017=2803:0018:02:2a01 0019=2803:001a:02:2aa6 0028=2800:ffff:0000180d-0000-1000-8000-00805f9b34fb 0029=2803:002a:10:00002a37-0000-1000-8000-00805f9b34fb 002b=2803:002c:02:00002a38-0000-1000-8000-00805f9b34fb 002d=2803:002e:08:00002a39-0000-1000-8000-00805f9b34fb [Endpoints] group contains: :::: String First field is the endpoint type, followed by codec type and delay reporting and its capabilities as hexadecimal encoded string. LastUsed:: String LastUsed has two fields which are the local and remote seids as hexadecimal encoded string. [NameResolving] group contains: FailedTime Integer The last time we failed to complete name resolving procedure, measured from an arbitrary, fixed point in the past. Info file format ================ Info file may includes multiple groups (General, Device ID, Link key and Long term key) related to a remote device. [General] group contains: Name String Remote device friendly name Alias String Alias name Class String Device class in hexadecimal, i.e. 0x000000 Appearance String Device appearance in hexadecimal, i.e. 0x0000 SupportedTechnologies List of List of technologies supported by strings device, separated by ";" Technologies can be BR/EDR or LE AddressType String An address can be "static" or "public" Trusted Boolean True if the remote device is trusted Blocked Boolean True if the remote device is blocked Services List of List of service UUIDs advertised by strings remote in 128-bits UUID format, separated by ";" [DeviceID] group contains: Source Integer Assigner of Device ID Vendor Integer Device vendor Product Integer Device product Version Integer Device version [LinkKey] group contains: Key String Key in hexadecimal format Type Integer Type of link key PINLength Integer Length of PIN [LongTermKey] group contains: Key String Long term key in hexadecimal format Authenticated Boolean True if remote device has been authenticated EncSize Integer Encrypted size EDiv Integer Encrypted diversifier Rand Integer Randomizer [PeripheralLongTermKey] group contains: Same as the [LongTermKey] group, except for peripheral keys. [ConnectionParameters] group contains: MinInterval Integer Minimum Connection Interval MaxInterval Integer Maximum Connection Interval Latency Integer Connection Latency Timeout Integer Supervision Timeout [LocalSignatureKey] and [RemoteSignatureKey] groups contain: Key String Key in hexadecimal format Counter Integer Signing counter Authenticated Boolean True if the key is authenticated [ServiceChanged] This section holds information related to Service Changed characteristic of GATT core service. CCC_LE Integer CCC value for LE transport CCC_BR/EDR Integer CCC value for BR/EDR transport