signalbackup-tools

# signalbackup-tools Tool to work with backup files generated by the Signal Android application (https://signal.org/). The tool is provided as-is, there may be bugs. The tool and I are not affiliated with or endorsed by the Signal Foundation. - [Important Note](#important-note) - [Requirements](#requirements) - [Obtaining](#obtaining) - [Windows binary](#windows) - [macOS](#macos) - [Linux packages](#linux_packages) - [Compiling](#compiling) - [Running](#running) - [Dump decrypted database to disk](#dump) - [Dump media to disk](#dumpmedia) - [Fixing broken backups](#fix) - [Export HTML, TXT, CSV & XML](#export) - [Cropping to certain conversations or dates](#crop) - [Merging backups](#merge) - [Importing conversations from Signal Desktop](#desktop) - [Importing conversations from JSON file / Telegram](#json) - [Deleting/Replacing attachments](#deleting_attachments) - [Operations for Signal Desktop](#desktop_functions) - [Various](#various) - [Advanced options](#advanced) - [Future plans](#future-plans) - [Donate](#donate) ### Important Note Signal is an actively developed application and consequently, the database format changes regularly. Often the changes do not affect the backup file format or the working of this program, but every once in a while a change does break (some of) the functionality of this program. It has happened before and it will happen again. Sometimes I fix it within hours, but when I am short on time, it may take a little longer. Any breakage will be dealt with as soon as I have some spare time. This tool first came in to (public) existence to help fix a few issues in the early backup implementation in Signal Android. Over time much more functionality has been added to this tool. Unfortunately, some of the more experimental functions have occassionally _caused_ of a few issues. For these see [ERRATA](ERRATA.md). ### Requirements To compile this project, current stable released versions of the following are needed: - A C++ compiler supporting at least the C++17 standard (the higher the standard, the better) (between [github actions](https://github.com/bepaald/signalbackup-tools/actions) and local builds, it is tested on around 15 different versions of [GCC](https://gcc.gnu.org), [Clang](https://clang.llvm.org) and MSVC). - [OpenSSL](https://www.openssl.org/) (any reasonably recent version from either the 3.X or 1.1x series) - [SQLite3](https://www.sqlite.org/) (any reasonably recent version) - Only on Linux: [dbus](https://www.freedesktop.org/wiki/Software/dbus/). Optional, but required by default. See the [compiling](#compiling) section to build without `dbus`. If the program is compiled without `dbus`, operations that need to open the Signal Desktop client database will not work unless the decrypted encryption key is manually provided. Note that some Linux distributions split their packages depending on whether they are used for compiling programs or not. For example, the `OpenSSL` dependency may require you to install `libssl-dev` (on Debian-like systems), or `openssl-devel` (on Red Hat-like systems). If you need help with this specifically, there are detailed instructions for some common Linux distributions in the [compiling](#compiling) section below (under 'CMake'). ### Obtaining **Windows binary** For the most recent Windows executable, check [the releases page](https://github.com/bepaald/signalbackup-tools/releases). This executable is a static build, cross compiled from my Arch Linux system. It is only minimally tested, but generally appears to work just fine. Note for Windows users: this is a command line application. This means you can not just double-click the executable to run it, you need to run it from a terminal. Common terminals for Windows are `cmd` (Command Prompt) and `PowerShell`. An example of running the program on Windows 10 can be seen [here](https://github.com/bepaald/signalbackup-tools/issues/148#issuecomment-1732375861). **Linux packages** - For **Arch** users an AUR package [is available](https://aur.archlinux.org/packages/signalbackup-tools-git). - For **Ubuntu and derivatives** a PPA is provided [here](https://launchpad.net/~olek-osikowicz/+archive/ubuntu/signalbackup-tools), thanks to @olek-osikowicz (https://github.com/bepaald/signalbackup-tools/issues/312). - A pre-built rpm for **openSUSE** is available [here](https://software.opensuse.org/package/signalbackup-tools?search_term=signalbackup-tools), thanks to @marfrh (https://github.com/bepaald/signalbackup-tools/issues/205). - The program is also available in `nixpkgs` as [`signalbackup-tools`](https://search.nixos.org/packages?channel=unstable&type=packages&query=signalbackup-tools) and can be installed on **NixOS** or any system that supports the [Nix package manager](https://nixos.org/manual/nix/stable/). For those looking for more information on installing and running the Nix package, or those wanting to help others, there is an issue where information can be found and posted [here](https://github.com/bepaald/signalbackup-tools/issues/149). - Alternatively, a Dockerfile has been kindly provided by David J. Meier, and is available at his gitlab page: . **macOS** A homebrew formula is provided in [HomebrewFormula/signalbackup-tools.rb](https://raw.githubusercontent.com/bepaald/signalbackup-tools/master/HomebrewFormula/signalbackup-tools.rb). To install on macOs with [homebrew set up](https://brew.sh/): 1. `brew tap bepaald/signalbackup-tools https://github.com/bepaald/signalbackup-tools` 2. `brew install --HEAD signalbackup-tools` Alternatively, you can download the formula to your machine and run `brew install --HEAD --formula [path/to/signalbackup-tools.rb]`. Once installed, the program can be upgraded when necessary by running `brew upgrade --fetch-HEAD --formula signalbackup-tools`. Manually compiling should also be possible assuming the dependencies are installed, for more info see [here](https://github.com/bepaald/signalbackup-tools/issues/9), or more recently [here](https://github.com/bepaald/signalbackup-tools/issues/85). macOS users might also consider the aforementioned [Nix package](https://search.nixos.org/packages?channel=unstable&type=packages&query=signalbackup-tools). **Compiling** To compile the program, first make sure the [dependencies](#requirements) are installed. Then three main options are available: - CMake. Make sure to have `cmake` installed. On Linux this method also requires `pkg-config` (unless building without `dbus`). From the project directory, run: ```Shell $ cmake -B build -DCMAKE_BUILD_TYPE=Release $ cmake --build build -j $(nproc) ``` To build without `dbus` (and `pkg-config`), add `-DWITHOUT_DBUS=1` to the first command.

Detailed compilation instructions for Debian-based systems (Ubuntu, Debian, Mint, and others) (click to show)

Below is the terminal output for installing the dependencies and compiling the program on a default Ubuntu 24.04 (slightly abbreviated). Start by opening your preferred terminal emulator. Then you should be able to copy and paste the commands below, one after the other. ``` … ``` The program is now successfully built in the subdirectory `build/`, and can simply be run from there (ie. `./build/signalbackup-tools [options]`). Alternatively, you can move the program to some directory that is in your $PATH to run it from any location without specifying the full path.

Detailed compilation instructions for Red Hat-based systems (Fedora, RHEL) (click to show)

Below is the terminal output for installing the dependencies and compiling the program on a default Fedora 41 installation (slightly abbreviated). Start by opening your preferred terminal emulator. Then you should be able to copy and paste the commands below, one after the other. ``` … ``` The program is now successfully built in the subdirectory `build/`, and can simply be run from there (ie. `./build/signalbackup-tools [options]`). Alternatively, you can move the program to some directory that is in your $PATH to run it from any location without specifying the full path.

- The bash script. In the project directory is a bash script `BUILDSCRIPT.bash`. Simply run it: ```Shell $ ./BUILDSCRIPT.bash ``` To build without `dbus`, add `--config without_dbus` to the above command. The script can of course be edited at will to change compilation behavior. The flags can also be changed on the command line when running, for example to build with `clang++` instead of `g++`, simply run `$ CXX=clang++ ./BUILDSCRIPT.bash`. - Manually. The program can be manually compiled simply by running `g++ -std=c++20 */*.cc *.cc -lcrypto -lsqlite3`. On linux, by default one needs to add the location of the dbus headers and libraries (simplest way, add: `$(pkg-config --cflags --libs dbus-1)`). Alternatively, to build on Linux without `dbus`, add `-DWITHOUT_DBUS=1`. On macOS, the program must be linked to the Security and CoreFoundation frameworks by adding `-framework Security -framework CoreFoundation` to the build command. Any compiler flags you feel useful can be added, personally I use at least `-O3 -Wall -Wextra`. When compiling with an old compiler version (gcc 8.x or clang <= 7), also add the -lstdc++fs flag and replace -std=c++20 with -std=c++17. ### Running > [!TIP] > In all examples below, one or more passphrases are provided on the command line. If so desired, these can be omitted in which case you are prompted for the passphrase at runtime. In its simplest form, this tool is run as such: ``` signalbackup-tools [input] [passphrase] ``` This will open the file `input` using the provided `passphrase`, and do nothing with it. If an output file is supplied the backup is written to that file: ``` signalbackup-tools [input] [passphrase] --output [output] ``` Optionally, a new passphrase can be provided for the output file with the option `--opassphrase`, or `-op` for short. If not provided, as in the above example, the input passphrase is used again. **Dump decrypted database to disk** The program can dump the decrypted backup components to a directory, or read the contents of a directory and pack and encrypt it back into a valid backup file. When dumping, make sure the directory to dump to is empty to start with. In theory, the decrypted files could be edited before re-encrypting. The tool can be called the same as above, except the output should be a directory: ``` signalbackup-tools [input] [passphrase] --output [outputdirectory] ``` To skip exporting media (like message attachments, avatars and stickers), add the option `--onlydb`. To re-encrypt the contents of a directory into a valid backup file, use the directory as `input` and provide the `--output` and `--opassphrase` options. Example (click to show)

``` … ``` _NOTE The original and new files are not actually guaranteed to be identical, it just so happens that in this case the AvatarFrames are read from the filesystem in the order they appeared in the original._

**Dump media to disk** ##### Dumping message attachments To only export media attachments from one or all of the threads in a backup, run with `--dumpmedia` as follows: ``` signalbackup-tools [input] [passphrase] --dumpmedia [outputdirectory] ``` Where `outputdirectory` is an empty directory, or does not exist (in which case it will be created). To limit the export to certain threads, the option `--limittothread