mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-23 12:14:26 +08:00
832b594a25
This documents the use of StateDirecory environment variable which overwrites the default storage diretory when set.
362 lines
9.1 KiB
Plaintext
362 lines
9.1 KiB
Plaintext
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]
|
|
<manufacturer id> = <array of addresses>
|
|
|
|
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/<adapter address>/
|
|
./settings
|
|
./attributes
|
|
./admin_policy_settings
|
|
./cache/
|
|
./<remote device address>
|
|
./<remote device address>
|
|
...
|
|
./<remote device address>/
|
|
./info
|
|
./attributes
|
|
./ccc
|
|
./<remote device address>/
|
|
./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:
|
|
|
|
<xx>:<xx>:<xx>::<xx...> String First field is the endpoint type,
|
|
followed by codec type and delay
|
|
reporting and its
|
|
capabilities as hexadecimal encoded
|
|
string.
|
|
LastUsed:<xx>:<xx> 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
|