Image replicator generic

Image Capture

If no valid images exist on the booted USB drive, the image capture process starts automatically. Startup scripts will check if the single partition of the USB drive can be expanded and do so if it is possible. If this process fails, image capture will be aborted and the red LED will blink to indicate a failure.

While in progress, the red LED will remain solid while the green LED flashes once per second. Upon completion, the red LED turns off and the green LED will slowly blink to indicate success, while a blinking red LED indicates a failure. Note that while in progress, the USB disk is mounted read-write. It is not recommended to power off the unit while the image capture is in progress.

To help diagnose failures, files in /tmp/logs/ contain output from each capture process.

For each media present on the unit (SD/eMMC/SATA/etc.), the image capture process will do the following:

1. Copy the whole disk image to an appropriately named file on the USB drive, e.g. sdimage.dd, no data is written to the source media and it is never mounted. The source disk can follow our stock partition layout, or implement a customized one.
2. Perform an fsck on the Linux rootfs in the image file. Note that, if deviating from our standard partition layout, it may be necessary to modify the scripts handling the capture process.
3. Perform a loopback mount of the Linux rootfs in the image file and sanitize the filesystem. The sanitization process removes temporary files (e.g. /log/ files), unique files (e.g. ssh private key files, machine ID files), adds a file to indicate that it is a custom image with the date as its contents, etc. The full list of operations can be found in this script. It may be necessary to modify this file for unique situations.
4. If the partition layout uses only a single partition, the filesystem is packed in to a tarball which is appropriately named and compressed, e.g. sdimage.tar.xz. The image file is then unmounted and removed.
5. If the partition layout uses multiple partitions, then the image file is then unmounted, an md5sum of the image file taken, compressed to an appropriately named file, e.g. emmcimage.dd.xz, and then an md5sum of the compressed image is taken.

Note that when using this process, the USB drive used must be sized large enough to handle multiple compressed images as well as the uncompressed copy of the media image actively being worked with. If the image capture process runs out of space, the process will indicate a failure.

The images files captured are saved to the root folder of the USB disk. Upon completion, it is safe to remove power or unplug the USB drive.

For more details on the image capture process, see this script.

Image Write

This process is used to write existing images to media on a target unit. If appropriately named disk images or tarballs (see table below) are present in the root folder of the USB drive when booted, then the startup scripts will start the image writing process. The latest disk images we provide can be downloaded from our FTP site, see the backup and restore section for links to these files.

While in progress, the red LED will remain solid while the green LED flashes once per second. Upon completion, the red LED turns off and the green LED will slowly blink to indicate success,;hile a blinking red LED indicates a failure. Note that the USB drive remains read-only through the entire process, but target devices may be mounted or actively written. It is not advised to remove power or the USB drive until the whole process has completed.

To help diagnose failures, files in /tmp/logs/ contain output from each writing process.

Note that the script expects images and tarballs to have specific names. When using an ext2/3/4 filesystem on the USB drive, symlinks can be used. The following table is the list of valid file names:

Target device	Accepted filenames	Description
SD Card	sdimage.tar.xz sdimage.tar.bz2 sdimage.tar.gz sdimage.tar	Tar of the filesystem. This will repartition the SD card to a single partition and extract this tarball to the filesystem. If present, a file named /md5sums.txt in the tarball will have its contents checked against the whole filesystem after the tarball is extracted. This md5sums.txt file is optional and can be omitted, but it must not be blank if present. This file is present in our official images and is created during image capture with the Image Replicator tool.
	sdimage.dd.xz sdimage.dd.bz2 sdimage.dd.gz sdimage.dd	Disk image of the card. This will be written to the SD card block device directly. If present on the USB drive, a file named sdimage.dd.md5 will be used to verify the data written to the SD card against this checksum. This file is provided with our official images and is created during image capture with the Image Replicator tool.
eMMC	emmcimage.tar.xz emmcimage.tar.bz2 emmcimage.tar.gz emmcimage.tar	Tar of the filesystem. This will repartition the eMMC to a single partition and extract this tarball to the filesystem. If present, a file named /md5sums.txt in the tarball will have its contents checked against the whole filesystem after the tarball is extracted. This md5sums.txt file is optional and can be omitted, but it must not be blank if present. This file is present in our official images and is created during image capture with the Image Replicator tool.
	emmcimage.dd.xz emmcimage.dd.bz2 emmcimage.dd.gz emmcimage.dd	Disk image of the card. This will be written to the eMMC block device directly. If present on the USB drive, a file named emmcimage.dd.md5 will be used to verify the data written to the SD card against this checksum. This file is provided with our official images and is created during image capture with the Image Replicator tool.
SATA	sataimage.tar.xz sataimage.tar.bz2 sataimage.tar.gz sataimage.tar	Tar of the filesystem. This will repartition the first SATA drive with a single partition and extract this tarball to the filesystem. If present, a file named /md5sums.txt in the tarball will have its contents checked against the whole filesystem after the tarball is extracted. This md5sums.txt file is optional and can be omitted, but it must not be blank if present. This file is present in our official images and is created during image capture with the Image Replicator tool.
	sataimage.dd.xz sataimage.dd.bz2 sataimage.dd.gz sataimage.dd	Disk image of the card. This will be written to the first SATA block device directly. If present on the USB drive, a file named sataimage.dd.md5 will be used to verify the data written to the SD card against this checksum. This file is provided with our official images and is created during image capture with the Image Replicator tool.

Upon completion, it is safe to remove power or unplug the USB drive.

For more details on the image write process, see this script.