Backup and Restore
Backup and restore mechanism¶
Whitebox provides a way to create device backups that can be restored later. This is useful for preserving device configurations and moving between devices.
For creating and restoring backups, you can use the export-whitebox-data and
import-whitebox-data commands.
First, you'll need to connect to the device.
Connecting to Your Whitebox Device¶
Either connect a screen and keyboard to your Orange Pi, or find its IP to access it from another computer using the following command, which will list all the IPs open for connection on the SSH server port, which should include your Orange Pi:
replacing 192.168.1.0/24 with your local network IP range. You can SSH into
your Orange Pi using:
replacing 192.168.1.120 with the IP identified via nmap.
The password for the whitebox user should be whitebox by default, or the
one you set during installation.
Creating a Backup¶
After connecting to your Whitebox device, you can create a backup by running the following:
By default, this will create a backup with all your data to a file named
whitebox-data-export.tar.gz, which includes your configurations and any
recorded media.
You should not perform any operations in Whitebox while the backup is being created.
There are several options to customize the backup process:
-t FILE/--target FILE: Specify a different output file name for the backup-l/--include-logs: Include application logs in the backup-s/--system-logs: Include system logs in the backup
Additionally, you can exclude certain data from the backup. Note that backups using these might not be importable, so make sure you know what you're doing with them. You have the following options:
--no-database: Exclude the database from the backup--no-media: Exclude recorded media files from the backup--no-archive: Do not create an archive file; instead, just prepare the data for export in a temporary directory that'll be printed to the console
You can run ./bin/export-whitebox-data --help to see all available options.
Once a backup is created, you can transfer the backup file to your computer using
scp or any other file transfer method that you prefer.
Restoring a Backup¶
Restoring a backup will overwrite existing data on the device. In case it has any data you want to keep, make sure to create a backup before proceeding.
After connecting to your Whitebox device, you can restore a backup by running the following:
By default, this will import the database and recorded media from the specified backup file.
You should not perform any operations in Whitebox while the backup is being restored.
There are several options to customize the restore process:
--no-db: Do not restore the database from the backup--no-media: Do not restore recorded media files from the backup
You probably don't need the above options, as loading only a part of the backup may cause Whitebox to be inoperational.
You can run ./bin/import-whitebox-data --help to see all available options.
Anatomy of a Backup File¶
Backup files are .tar.gz archives that contain the following structure:
database-dump.sql: SQL dump of the Whitebox databasemedia/: Directory containing recorded media fileslogs/: Directory containing application logs (if included)system-logs/: Directory containing system logs (if included)metadata.json: Metadata about the backup, such as version information, creation date, and included/excluded components
If you're creating a backup file to diagnose an issue with Whitebox, including
logs can be very helpful. Note that some of the logs might contain info only
for a single device boot (e.g. system logs' dmesg output).
Some of them can also be very verbose and contain sensitive information, so be cautious when sharing them with others. For example, some countries may have specific regulations about sharing RF-acquired or GPS data.
Backup and restore the entire SD card¶
Sometimes, you might want to backup or clone the entire SD card used by your
Whitebox device. You can do this using tools like dd.
Note that the instructions below may be dangerous if you specify the wrong device name, as you may overwrite important data. Always double-check the device names before running the commands.
If you are not comfortable with this, we advise you to use the backup and restore mechanism described above instead.
Backing up the SD card¶
To create a backup image of your SD card, first identify the device name of
your SD card. You can use the lsblk command on Linux, or diskutil list on macOS.
You are probably looking for a device like /dev/sdX on Linux or
/dev/diskN on macOS, where X is a letter and N is a number.
Once you've identified it, you can create a backup image using the following command:
# replace DEVICE_PATH with your SD card device (e.g., /dev/sdX)
# replace PATH_TO_WRITE_IMG_TO with the path where you want to save the image
sudo dd if=DEVICE_PATH of=PATH_TO_WRITE_IMG_TO bs
# For example:
sudo dd if=/dev/sda of=~/whitebox-sdcard-backup.img bs
This command will create a bit-for-bit copy of the SD card and save it as an
.img file that you can later use to restore the SD card or clone it to another
SD card. Note that this process will create a file as large as the SD card's
TOTAL capacity, even if there's unused space, so make sure you have enough space.
Initializing a demo environment from an SD card image¶
Whitebox provides a utility to create a demo environment from an SD card image. This is useful for testing or development purposes without needing to write the image to an actual SD card.
This utility is intended to be used on a fresh Linux system, dedicated to creating the demo environment, and it should not be used on any other systems. It performs a destructive operation - it will stop all Docker containers, and remove all Docker images, volumes, and networks in the process, as a way to ensure a clean environment for the demo.
Once again, DO NOT USE THIS ON ANY SYSTEM THAT HAS DATA YOU WANT TO KEEP. We are not responsible for any data loss that may occur from using this utility.
To create a demo environment from an SD card image, you first need to have these installed:
- Docker
jqmake
After installing these and downloading the SD card image, you'll first need to download the provisioning script. As any potentially existing Whitebox installation will likely be removed as part of the process, it is advisable not to run this from an existing Whitebox installation but download it separately.
To download it to /provision-demo-from-img.py and run it with the path to your
SD card image, you can run the following command:
sudo curl https://gitlab.com/whitebox-aero/whitebox/-/raw/main/bin/provision-demo-from-img.py /provision-demo-from-img.py
sudo bash /provision-demo-from-img.py -i PATH_TO_SD_CARD_IMAGE.img
This will download the provisioning script
and run it with the specified SD card image. The script will mount the image to
a loop device, extract necessary data, remove any existing Docker containers and
images to ensure the clean environment, and then set up the demo Whitebox
environment using Docker. You will be prompted to adjust the .env file contents
during the process.
Additionally, if you'd like to initialize the demo environment with a specific
branch's code, you can provide a -b BRANCH_NAME argument, for example: