Create backups of an Android device over USB (requires adb and TWRP recovery)
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-outdoes 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
Z00T; and other operating systems, various versions of Windows and Mac OS X.
tetherback requires Python 3.3+. In addition, it depends on:
adb(Android Debug Bridge) command-line tools
tabulatepackages from PyPI (fetched automatically during
pip install; see below)
pip3to automatically fetch Python dependencies. (Note that on most systems,
pipinvokes the Python 2.x version, while
pip3invokes 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
Boot your device into TWRP recovery and connect it via USB. Ensure that it's visible to
$ adb devices List of devices attached 0123deadbeaf5f5f recovery
Make a TWRP-style backup over ADB. This saves a gzipped image of the
boot.emmc.win, and saves the contents of the
/datapartitions as tarballs named
$ tetherback tetherback v0.8 Found ADB version 1.0.32 Using default transfer method: adb exec-out pipe (--exec-out) Device reports kernel 3.4.0-bricked-hammerhead-twrp-g7b77eb4 Device reports TWRP version 3.0.0-0 Reading partition map for mmcblk0 (29 partitions)... partition map: 100% Reading partition map for mmcblk0rpmb (0 partitions)... partition map: 100% Saving backup images in ./twrp-backup-2016-07-03--14-53-29/ ... Saving partition boot (mmcblk0p19), 22 MiB uncompressed... boot.emmc.win: 100% 4.0 MiB/s 16.3 MiB Saving tarball of mmcblk0p25 (mounted at /system), 1024 MiB uncompressed... system.ext4.win: 100% 2.5 MiB/s 299.7 MiB Saving tarball of mmcblk0p28 (mounted at /data), 13089 MiB uncompressed... data.ext4.win: 100% 2.0 MiB/s 804.0 MiB
Make a "nandroid"-style backup over ADB. This saves gzipped images of the partitions labeled
$ tetherback -N tetherback v0.8 Found ADB version 1.0.32 Using default transfer method: adb exec-out pipe (--exec-out) Device reports kernel 3.4.0-bricked-hammerhead-twrp-g7b77eb4 Device reports TWRP version 3.0.0-0 Reading partition map for mmcblk0 (29 partitions)... partition map: 100% Time: 0:00:03 Reading partition map for mmcblk0rpmb (0 partitions)... partition map: 100% Saving backup images in nandroid-backup-2016-07-03--18-15-03/ ... Saving partition boot (mmcblk0p19), 22 MiB uncompressed... mmcblk0p19: 100% 3.07 MB/s 16.3 MiB Saving partition system (mmcblk0p25), 1024 MiB uncompressed... mmcblk0p25: 100% 1.76 MB/s 343.7 MiB Saving partition userdata (mmcblk0p28), 13089 MiB uncompressed... mmcblk0p28: 100% 1.80 MB/s 6.4 GiB
Extra partitions can be included with the
--extra-rawoptions; for example,
-X modemst1 -X modemst2to backup the Nexus 5 EFS partitions.
--extra-raw, the extra partition will always be saved as a raw image, rather than as a tarball, even if it is a mountable filesystem and tetherback is run in TWRP backup mode.
The partition map and backup plan will be printed with
--dry-runto only print it, and skip the actual backup). For example, the following partition map and backup plan will be shown for a Nexus 5 with the standard partition layout:
BLOCK DEVICE PARTITION NAME SIZE (KiB) MOUNT POINT FSTYPE -------------- ---------------- ------------ ------------- -------- mmcblk0p1 modem 65536 ... mmcblk0p19 boot 22528 ... mmcblk0p25 system 1048576 /system ext4 ... mmcblk0p28 userdata 13404138 /data ext4 mmcblk0p29 grow 5 Total: 15388143
PARTITION NAME FILENAME FORMAT
boot boot.emmc.win gzipped raw image system system.ext4.win tar -cz -p userdata data.ext4.win tar -cz -p --exclude="media*" --exclude="*-cache"
Additional options allow exclusion or inclusion of standard partitions:
-M, --media Include /data/media* in TWRP backup (deprecated: default behavior) -D, --data-cache Include /data/*-cache in TWRP backup -R, --recovery Include recovery partition in backup -C, --cache Include /cache partition in backup -U, --no-userdata Omit /data partition from backup (implies --no-media) -E, --no-media Omit /data/media* from TWRP backup -S, --no-system Omit /system partition from backup -B, --no-boot Omit boot partition from backup
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:
Clearly I'm not the only one with this problem:
One of the very annoying issues with
adb shellis 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
By default, tetherback uses TCP forwarding with older versions of
adb, and an
exec-outbinary pipe with newer versions (1.0.32+). If you have problems, please try
--base64for a slow but reliable transfer method, and please report any data corruption issues. If your host OS is Linux,
--pipeshould 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)
GPL v3 or newer