tdbtool

tdbtool [OPTIONS] TDB_FILE [COMMAND] [KEY] [VALUE]

tdbtool TDB_FILE info
tdbtool TDB_FILE dump
tdbtool TDB_FILE create
tdbtool TDB_FILE check
tdbtool TDB_FILE delete KEY
tdbtool TDB_FILE store KEY VALUE
tdbtool TDB_FILE keys

-H, --hex
    Display keys and values in hexadecimal format. This is the default output format for 'dump' and 'keys' commands.

-s, --string
    Interpret keys and values as human-readable strings. Useful for viewing textual data.

-v, --verbose
    Produce more verbose output, often showing additional details about operations.

info
    Display information about the TDB file's header, such as its version, size, and number of records.

dump
    Dump all key-value pairs stored in the TDB file. By default, outputs in hexadecimal.

create
    Create a new, empty TDB file. If the file already exists, it will be truncated.

check
    Perform a consistency check on the TDB file, verifying its integrity.

delete KEY
    Delete the record associated with the specified KEY from the TDB file.

store KEY VALUE
    Store a new key-value pair or update an existing one. If the KEY already exists, its VALUE will be overwritten.

keys
    Dump only the keys present in the TDB file. Useful for quickly listing entries without their values.

tdbtool is a command-line utility used for inspecting, creating, and modifying TDB (Trivial Database) files. TDB is a simple, lightweight key-value database often employed by the Samba suite to store various kinds of persistent data, such as share definitions, lock information, user mapping, and other internal state.

This tool provides a direct interface to manipulate these database files, allowing administrators and developers to examine the contents of a TDB file, add new records, update existing ones, or delete entries. It's particularly useful for debugging issues related to Samba's internal data, recovering from corruption, or performing manual data adjustments when necessary. While powerful, direct modification requires caution, as incorrect operations can lead to data corruption or service instability. By default, tdbtool displays keys and values in hexadecimal format, but it can also interpret them as strings for easier readability.

Direct manipulation of TDB files using tdbtool carries risks. Incorrect operations, especially when modifying or deleting records, can lead to data corruption within the TDB file. This can, in turn, cause critical Samba services to malfunction or even fail to start. It is highly recommended to always back up any TDB file before attempting modifications. Additionally, modifications should ideally be performed on files that are not actively in use by a running Samba daemon or other services to prevent conflicts or inconsistent states.

By default, tdbtool expects and outputs keys and values as hexadecimal byte sequences. This is the raw format in which TDB stores data. For example, a key 'users' might be displayed as '7573657273'. To work with human-readable strings, especially for textual data, use the -s or --string option. When using store, if -s is not specified, you'll need to provide hexadecimal representations of the key and value.

Typical uses for tdbtool include:
Debugging: Examining the contents of TDB files (e.g., 'locking.tdb', 'secrets.tdb') to understand Samba's internal state.
Corruption Recovery: In rare cases of TDB file corruption, tdbtool might be used to attempt to delete corrupted records or check file integrity.
Advanced Administration: Manually adding or modifying specific entries for very specific configurations or troubleshooting scenarios.
Data Migration/Inspection: Viewing TDB contents before or after Samba upgrades or reconfigurations.

tdbtool is an integral part of the Samba suite, an open-source implementation of the SMB/CIFS networking protocol. It was developed by Andrew Tridgell and the Samba Team as a utility to manage TDB (Trivial Database) files, which are a simple, high-performance database format designed specifically for Samba's internal data storage needs. TDB itself was created to provide a lightweight, efficient key-value store without the overhead of more complex database systems, making tdbtool essential for debugging, maintenance, and advanced administration of Samba installations.

samba(8), smb.conf(5), tdb(3)