search

dlenski / tetherback

Create backups of an Android device over USB (requires adb and TWRP recovery)
156 stars 22 forks source link

readme

IMPORTANT
This project is mostly-abandoned.
- Every version of Android, and sometimes every new device, appears to do something weird to break it.
- I only own one Android phone, and it's 7 years old, and on an obsolete version.
- Most of the software I write is designed for desktop Linux. As I also noted in another issue, bug reports and other feedback from users of Android apps are of a strikingly poor quality in comparison.
- Conclusion: I lack the motivation or ability to maintain this in any substantial way.
- If you want to fork it, fork it. If you want to take over maintaining it, email me.

tetherback

Tools to create TWRP and nandroid-style backups of an Android device via a USB connection, without using the device's internal storage or SD card.

To guarantee against backup corruption during transfer, it generates md5sums of the backup files on the device and then verifies that they match on the host.

WARNING: This is a work in progress. I have personally tested it on the following device/recovery/host combinations…

Device Codename TWRP recovery adb Host OS Comments
LG/Google Nexus 5 hammerhead v2.8.5-0 v1.0.32 Ubuntu amd64 adb exec-out does not work
LG/Google Nexus 5 hammerhead v3.0.0-0 v1.0.31 Ubuntu amd64 working
LG/Google Nexus 5 hammerhead v3.0.0-0 v1.0.32 Ubuntu amd64 working
LG/Google Nexus 5 hammerhead v3.0.2-0 v1.0.32 Ubuntu amd64 working
Samsung Galaxy S4 L720T jfltespr v3.0.2-0 v1.0.32 Ubuntu amd64 working
Moto G4 Play harpia v3.0.2-r5 v1.0.32 Ubuntu amd64 working

Other users have reported success—and issues ☺—with other devices, including picassowifi, cancro, Z00T; and other operating systems, various versions of Windows and Mac OS X.

Requirements and installation

tetherback requires Python 3.3+. In addition, it depends on:

Install with pip3 to automatically fetch Python dependencies. (Note that on most systems, pip invokes the Python 2.x version, while pip3 invokes the Python 3.x version.)

# Install latest development version
$ pip3 install https://github.com/dlenski/tetherback/archive/HEAD.zip

# Install a tagged release
# (replace "RELEASE" with one of the tag/release version numbers on the "Releases" page)
$ pip3 install https://github.com/dlenski/tetherback/archive/RELEASE.zip

Usage

Boot your device into TWRP recovery and connect it via USB. Ensure that it's visible to adb:

$ adb devices
List of devices attached
0123deadbeaf5f5f    recovery

Additional options

Motivation

I've been frustrated by the fact that all the Android recovery backup tools save their backups on a filesystem on the device itself.

This is problematic for several reasons:

  1. Most modern Android smartphones don't have a microSD card slot.
  2. There may not be enough space on the device's own filesystem to back up its own contents.
  3. Getting the large backup files off of the device requires an extra, slow transfer step.

Clearly I'm not the only one with this problem:

I found that @inhies had already created a shell script to do a TWRP-style backup over USB (Gist) and decided to try to put together a more polished version of this.

Issues

One of the very annoying issues with adb is that adb shell is not 8-bit-clean: line endings in the input and output get mangled, so it cannot easily be used to pipe binary data to and from the device. The common workaround for this is to use TCP forwarding and netcat (see this answer on StackOverflow), but this is more cumbersome to code, and prone to strange timing issues. There is a better way to make the output pipe 8-bit-clean, by changing the terminal settings (another StackOverflow answer), though apparently it does not work with Windows builds of adb.

By default, tetherback uses TCP forwarding with older versions of adb, and an exec-out binary pipe with newer versions (1.0.32+). If you have problems, please try --base64 for a slow but reliable transfer method, and please report any data corruption issues. If your host OS is Linux, --pipe should be faster and more reliable.

  -t, --tcp             ADB TCP forwarding (fast, should work with any host
                        OS, but prone to timing problems)
  -x, --exec-out        ADB exec-out binary pipe (should work with any host
                        OS, but only with newer versions of adb and TWRP)
  -6, --base64          Base64 pipe (very slow, should work with any host OS)
  -P, --pipe            Binary pipe (fast, but probably only works
                        on Linux hosts)

License

GPL v3 or newer