NB scruss is not the author or maintainer of these files (same goes for seamusdemora, who assumed maintenance for this repo from scruss). Please take up any issues or questions in the Image File Utilities thread of the Raspberry Pi Forums site. IOW: This is a file repository only; no support is available here.
Files here are a toolset to create a backup of a running RPi OS to an SD card image file.
The files here are copies of those posted in the Raspberry Pi Forums site. The file attachments in this forum don't seem to be persistent, so this repo was created by user scruss (and now maintained by seamus) in an effort to ensure a current working copy of image-utils is always available through git.
I've used RonR's image-utils for several years now, and I've become a big fan. Image-utils creates a complete backup of a Raspberry Pi quickly and efficiently; these backups are rendered in the form of an "image file". The *.img format is ideal as a backup because it's a complete backup, it's portable, and it can be loop-mounted. In other words: If your system or SD card becomes corrupted, it can be restored to operation with minimal effort. This restoration requires 3 "ingredients", and about 5 minutes:
- The *.img file - created by routine/scheduled runs of
image-backupon your system - A spare micro SD card
Etcherto write the .img file to the micro-SD card
The speed and efficiency of image-backup are especially noteworthy. Because image-backup uses rsync for file copying/syncing, a backup requires only the storage space that is actually used by your system. This is unlike dd:
ddhas no way to tell what portions of your drive/SD card are being used vs. what what portions are not used becauseddhas no concept of a file. Consequently, addbackup of a 32 GB SD card requires: ...32GB!!- Because of this fundamental limitation,
ddis "v-e-r-y s-l-o-w".
By comparison, for my systems (Lite; running headless), a backup of a 32GB SD card requires typically a 3-5GB *.img file, and 5-10 minutes; that includes the time for network transfer.
Another efficiency of image-utils is its ability to update an *.img file. In other words, instead of creating an entire new *.img file from scratch, it can update an existing *.img file to incorporate any changes to the filesystems since the last backup. This ability to update further reduces the time required for a backup from 5-10 minutes to (potentially) seconds.
This repo was created to make a current copy of the RPi image-utils toolset available through git. There are many resources available online describing the use of git, so these instructions are minimal. If you have questions, please consult a tutorial of your own choosing. The instructions below reflect using bash from a Raspberry Pi OS terminal or SSH, and assume that git is installed:
$ cd && pwd
/home/pi
$ mkdir gitrepos # or use a directory of your own choosing
$ cd gitrepos
$ git clone https://github.com/seamusdemora/RonR-RPi-image-utils.gitCloning into 'RonR-RPi-image-utils'...
remote: Enumerating objects: 147, done.
remote: Counting objects: 100% (80/80), done.
remote: Compressing objects: 100% (58/58), done.
remote: Total 147 (delta 51), reused 35 (delta 21), pack-reused 67
Receiving objects: 100% (147/147), 52.04 KiB | 1.73 MiB/s, done.
Resolving deltas: 100% (87/87), done.
$ ls -la ~/gitrepos/RonR-RPi-image-utilstotal 84
drwxrwxr-x 4 pi pi 4096 Dec 3 17:46 .
drwxr-xr-x 7 pi pi 4096 Dec 3 17:53 ..
drwxrwxr-x 2 pi pi 4096 Dec 3 17:46 deprecated
drwxrwxr-x 8 pi pi 4096 Dec 3 17:46 .git
-rw-rw-r-- 1 pi pi 14017 Dec 3 17:46 image-backup
-rw-rw-r-- 1 pi pi 1534 Dec 3 17:46 image-check
-rw-rw-r-- 1 pi pi 3722 Dec 3 17:46 image-chroot
-rw-rw-r-- 1 pi pi 3406 Dec 3 17:46 image-compare
-rw-rw-r-- 1 pi pi 3115 Dec 3 17:46 image-info
-rw-rw-r-- 1 pi pi 1667 Dec 3 17:46 image-mount
-rw-rw-r-- 1 pi pi 5719 Dec 3 17:46 image-set-partuuid
-rw-rw-r-- 1 pi pi 4150 Dec 3 17:46 image-shrink
-rw-rw-r-- 1 pi pi 11832 Dec 3 17:46 README.md
-rw-rw-r-- 1 pi pi 4087 Dec 3 17:46 README.txt
$ cd ~/gitrepos/RonR-RPi-image-utils
$ git config pull.rebase false # this only needs to be done one time (the first time)
$ git pull # all subsequent updates require only this command Once you have all of the inage-utils files in your local git repository, you may find it's worthwhile to keep working copies in your PATH. This makes it easier to use them either directly from the command line, or (for example) in an cron job. Here's one way to do this:
cd
sudo install --mode=755 ~/gitrepos/RonR-RPi-image-utils/image-* /usr/local/sbinRefer to the Image File Utilities thread of the Raspberry Pi Forums site for documentation & support. This is offered only as an illustration/example:
To create a NEW image backup, use the sudo image-backup command; you will be prompted for inputs. The ones I typically use are shown below immediately following the question mark ?:
$ sudo image-backup
Image file to create? /mnt/SynologyNAS/rpi_share/raspberrypi3b/20230212_Pi3B_imagebackup.img
Initial image file ROOT filesystem size (MB) [2317]? 2400
Added space for incremental updates after shrinking (MB) [0]? 200
Create /mnt/SynologyNAS/rpi_share/raspberrypi3b/20230212_Pi3B_imagebackup.img (y/n)?y
This will take a few minutes depending on your model Pi, the size of your file system & other variables. Upon completion, you should find the image file you specified in your answer to the first question. This image file contains everything exactly as it was in your file system at the time of the backup. This image file may be written to an SD card, or mount-ed as another file system on your RPi.
To update the image file you have created is even easier; sudo image-backup <IMG_TO_UPDT>, or:
$ sudo image-backup /mnt/SynologyNAS/rpi_share/raspberrypi3b/20230212_Pi3B_imagebackup.imgIn other words, simply add the URL of the .img file you wish to update to the basic sudo image-backup command.
Usage: image-backup [options] [pathto/imagefile for incremental backup] -h,--help This usage description -i,--initial pathto/filename of image file [,inital size MB [,added space for incremental MB]] -n,--noexpand Do not expand filesystem on first run after restore -o,--options Additional rsync options (comma separated) -u,--ubuntu Ubuntu (Deprecated) -x,--extract Extract image from NOOBS (force BOOT partition to -01 / ROOT partition to -02)"
image-backup creates a backup of a running Raspbian system to a standard 'raw' image file that can be written to an SD card or a USB device with Etcher, imageUSB, etc. It will also perform incremental updates to an existing backup image file.
Running image-backup with no incremental backup file parameter will create an initial/full backup. If no -i/--initial option is included, image-backup will interactively prompt for an "Initial image file ROOT filesystem size (MB)", which can be any size as long as (1) it's large enough to hold the data contained on the device being backed up and (2) that amount of space is available on the destination device. image-backup will also prompt for an "Added space for incremental updates after shrinking (MB)" which will be added to the image file size after the full backup completes and the image file has been shrunk to the smallest size possible. The resulting image file will auto-expand the first time it's executed unless the -n/--noexpand option is included.
Running image-backup with a parameter of an existing image filename will incrementally update that image file. The -i/--initial option is ignored on incremental backups.
The -o/--options option permits including additional rsync options (comma separated).
Examples:
image-backup
image-backup /media/backup.img
image-backup --initial /media/backup.img,,5000 --noexpand --options --exclude-from=/home/pi/exclude.txt,--delete-excluded
Usage: image-check imagefile [W95|Linux]
where W95 checks the BOOT partition and Linux checks the ROOT partition. If neither is specified, Linux is assumed.
image-check will check the integrity of a standard 'raw' image file.
Usage: image-backup [options] pathto/imagefile -h,--help This usage description -u,--ubuntu Ubuntu (Deprecated)
image-chroot performs a linux 'chroot' to an image file. The current user will be 'root' and the current directory will be '/' in the image file. The host's root filesystem will be available at /host-root-fs. Use exit or ^D to terminate chroot.
Usage: image-backup [options] pathto/imagefile -h,--help This usage description -o,--options Additional rsync options (comma separated) -u,--ubuntu Ubuntu (Deprecated)
image-compare compares a running Raspbian system to an existing standard 'raw' image file and displays the incremental changes that image-backup would perform if run.
Usage: image-backup [options] pathto/imagefile -h,--help This usage description -u,--ubuntu Ubuntu (Deprecated)
image-info displays information about a standard 'raw' image file.
Usage: image-mount imagefile mountpoint [W95|Linux]
where W95 mounts the BOOT partition and Linux mounts the ROOT partition. If neither is specified, Linux is assumed.
image-mount mounts a standard 'raw' image file to allow it to be read or written as if it were a device.
Usage: image-set-partuuid imagefile [ hhhhhhhh-02 | hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh | random ]"
If no partuuid is specified, the current ROOT partuuid will be displayed.
image-set-partuuid sets the ROOT partition PARTUUID value of a standard 'raw' image file.
Usage: image-shrink imagefile [Additional MB]
where Additional MB is an optional additional amount of free space to be added.
image-shrink shrinks a standard 'raw' image file to its smallest possible size (plus an optional additional amount of free space).