Toolboxes started life often described as disposable containers – and that is still one of their major uses: install stuff, then try it out in the relative safety of a container, and lastly, cleanly dispose of it. Minimal risk, fuss and without pesky residual libraries and applications hanging around on the host long after you have finished.
So — why would you backup a Toolbox? Sometimes, they have more permanent uses, contain complex and lengthy installs, or are being used for critical applications. For example, Toolboxes can be used as a development environment, containing hardware associated drivers and applications. Or they could be used for an application you want to run in a container for which there is no Flatpak, or one that has requirements a Flatpak doesn’t satisfy. While they can be handy to use on Fedora Workstation, toolbox containers are often essential for Silverblue users since they offer an easy solution to installing applications that can’t successfully be installed by rpm-ostree. Or for applications that may not have a Flatpak version readily available. In the above situations a busted Toolbox can be a major headache. But if a backup exists, you can quickly restore a Toolbox or move it to another workstation.
The backup process uses Podman to create an image of an existing toolbox container, and save that image to an archive file. To restore the toolbox container, load the image from the archive file and then create a Toolbox from that image. The new toolbox container will be an identical copy of your backed up toolbox container.
It is important to note this process does not backup data, just what you have installed in the toolbox container. This includes packages installed from repositories or from a local rpm file using dnf. If you need to backup data, Podman’s commit command that will be used to capture an image of the toolbox container, has an option to include volumes attached to the container.
Creating a backup
To backup a toolbox container you will need it’s name and container ID which can be gotten by using toolbox list. For this example I am going to backup my golang development toolbox container, imaginatively named go.
$ toolbox list CONTAINER ID CONTAINER NAME CREATED STATUS IMAGE NAME 00ff783a102f go 5 weeks ago exited registry.fedoraproject.org/f32/fedora-toolbox:32
If the container’s status shows as running , you should stop it using podman container stop container_name. Although the commit command has a -p for pause option, make sure that the Toolbox is not running, which helps it initialize correctly when restored from backup.
$ podman container stop go
To create an image of the toolbox container use
$ podman container commit -p 00ff783a102f go-backup
Now to confirm the image has been created type…
$ toolbox list
You should get output similar to what is below…
IMAGE ID IMAGE NAME CREATED cfcb13046db7 localhost/go-backup:latest About a minute ago CONTAINER ID CONTAINER NAME CREATED STATUS IMAGE NAME 00ff783a102f go 5 weeks ago exited registry.fedoraproject.org/f32/fedora-toolbox:32
Now to save the backup image to a tar archive file using podman save -o backup-filename.tar backup-image-name.
$ podman save -o go.tar go-backup
Confirm the archive file, our toolbox container backup, was created.
$ ls go.tar
Do some tidying up, remove the backup image and, if needed, remove the original Toolbox.
$ podman rmi go-backup $ toolbox rm go
Restore a backup
To create an image from the backup file that was made above, you do it with the command podman load -i backup_filename.
$ podman load -i go.tar
Then you can confirm the image was created with…
$ toolbox list IMAGE ID IMAGE NAME CREATED cfcb13046db7 localhost/go-backup:latest 17 minutes ago
Now create a toolbox container from the restored image, with toolbox create ––container container_name ––image image_name, specifying the full repository and version tag as the image name.
$ toolbox create --container go --image localhost/go-backup:latest
Confirm that the toolbox was created.
$ toolbox list IMAGE ID IMAGE NAME CREATED cfcb13046db7 localhost/go-backup:latest 20 minutes ago CONTAINER ID CONTAINER NAME CREATED STATUS IMAGE NAME 34cef6b7e28d go 21 seconds ago configured localhost/go-backup:latest
Finally, you can test that the restored Toolbox works…
$ toolbox enter --container go
If you can enter the newly created toolbox container, you will see the toolbox prompt and will have successfully backed up and restored your Pet toolbox container.
Jens Petersen
Thanks for this useful article: it should be particularly useful for migrating or sharing toolbox images.
What I have been doing personally for my general toolbox containers is having a small toolbox initial setup script which I run in a newly created toolbox to install all the common packages I need for development like Emacs, compilers, etc. (I created it initially by noting down whenever I installed some missing package(s) into toolbox.)
I also have a small script (called sys-rpms) for recording all currently installed rpms in a system for completeness, though I find the above setup install script is really sufficient for me.
Vernay Bruno
Same here, using a basic script for common ground.
I am also a bit surprised that backuping the image is still a thing in the “Infrastructure as code” world. I guess everyone has its workflow, but I like to save my toolbox script with the project in git and it seems easier than managing backups.
Joe Fidler
Completely agree that backing up a toolbox is a bit clumsy a lot of the time – it’s often much easier to create the toolbox from fresh, especially if you use a script to automate setup inside the toolbox. I have found the backup method useful when a install involves drivers that cannot be pulled from repositories, or you are replicating a toolbox to multiple local machines where copying an image to a USB drive can save multiple downloads.