FAQ: Questions and answers about the Distrobox container tool

With the Linux tool Distrobox, you can turn your system into a Linux multi-talent, run various distributions in containers and are no longer restricted to the in-house package manager. We have already introduced this practical tool. Just a few commands are enough to get started, but the isolation of the containers can raise questions in day-to-day work. We provide answers to the most frequently asked questions.

Cloning containers

I have installed several packages in an Ubuntu container. How can I create a duplicate of it for testing?

If you want to clone the "ubuntu-ct" container, first stop it via distrobox stop ubuntu-ct. The following command then creates a clone under the name "ubuntu-klon":

distrobox create --clone ubuntu-ct -n ubuntu-klon

Tapping other image sources

The available images are not enough for me. Can I also use images from other sources?

Yes, Distrobox can tap into any sources as long as these so-called registries follow the standards of the Open Container Initiative (OCI). These include the Docker Hub and Quay.io from Red Hat. All you have to do is pass the URL to the appropriate image to the create command. The following command retrieves Arch Linux from the Docker Hub as an example:

distrobox create -i docker.io/library/archlinux -n dockerarch

Keep in mind that some of the images are not intended for operation under Distrobox. This often applies to containers that only contain a database, a web server or another server service.

Other architectures

Can I also run a distribution for the Raspberry Pi on my Intel system?

Yes, it works, although only with the handbrake on: Distrobox starts distributions for a different processor architecture via the Qemu emulator. As this in turn emulates a complete processor in software, the container runs more slowly.

In the background, Distrobox tells the Linux kernel how to run the programs in the container with Qemu via the so-called Binfmt interface. In addition to the appropriate Qemu emulators, you therefore also need any required Binfmt packages on the host system. Which packages you need to install in detail depends on your distribution: While qemu and qemu-linux-user are sufficient under openSUSE, you must install qemu-system, qemu-user-static and binfmt-support under Debian, Ubuntu and their derivatives.

In any case, you can then use Distrobox to create a container that is not intended for your processor – such as Fedora 41 for ARM64 computers:

distrobox create -i fedora:41-aarch64 -n fedora-arm64

You may ignore the warning displayed about the wrong image platform. If no image is available for ARM64 and you are using Docker or Podman, pass the option "--platform=..." to the container managers with the parameter -a:

distrobox create -a "--platform=linux/arm64" -i debian -n debian-arm64

Specify container service

How do I force Distrobox to use Docker instead of Podman in the background?

If several container managers are available, Distrobox prefers to use Podman. Use the environment variable DBX_CONTAINER_MANAGER to explicitly specify one of the three supported container services. In the following, Distrobox would start the containers with docker; alternatives are podman and lilipod:

export DBX_CONTAINER_MANAGER="docker"

Seal off containers

The applications in my container see all running processes of the host system and could, for example, terminate them maliciously. How do I prevent this?

When creating a new container, you can specifically prevent access to the processes of the host system and some other resources. To do this, you must pass the appropriate parameter(s) to distrobox create (see table "Parameters for access rights"). For example, the following command hides all processes from the programs in the container ubuntu-noproc:

distrobox create --unshare-process -i ubuntu -n ubuntu-noproc

Distrobox cannot subsequently change the restrictions once they have been selected. If you clone the container, you must also specify the parameters again, otherwise the duplicate will ignore the restrictions. But be careful: the restrictions do not put a container in a high-security prison. For example, the container can still access your home directory.

Change hostname

All my containers use the same hostname. How can I give each one an individual one?

By default, each container uses the host name of the host system. Distrobox also passes the corresponding configuration file /etc/hostname through to the container. If you give the container its own network environment via the parameter --unshare-netns, Distrobox will build the hostname from the container name and the name of the host system, such as ubuntu-ct.marvin.

However, you can also give each container its own host name. To do this, pass the parameter --hostname when creating the container.

distrobox create --hostname "rupert"  -i ubuntu -n ubuntu-rupert

The newly created container then uses "rupert" as the host name.

Mount folders and volumes

I have installed Google Chrome under /opt. How can I access this directory in the container?

For security reasons, containers may only access selected directories on the host system. When creating a container, you can add any other directories to the container using the --volume parameter:

distrobox create --volume /opt/google/chrome:/opt/chrome:rw -i ubuntu -n ubuntu-vol

Here Distrobox displays the directory /opt/google/chrome in the container under /opt/chrome, whereby the guest system in the container has read and write (rw) access to the directory contents. The notation with the colons follows the Docker specifications: The path on the host system is written after --volume, the folder in the container after the colon and optionally the access rights after another colon. Instead of the path on the host system, you can also specify a Docker volume. If you want to mount several directories, each needs its own --volume parameter.

Create multiple containers at the same time

I would like to set up several containers with different programming environments. Do I have to set up and start up each container individually?

No, it's easier: First you describe the configuration of the containers in a so-called manifest (distrobox.ini), which the distrobox assemble command then starts up and, if necessary, shuts down again. The structure of the text file is described in the Distrobox documentation.

Using distrobox.ini, distrobox assemble create creates the containers described therein. A distrobox assemble rm later destroys them all again.

Am I already inside?

How do I know if I am currently in a container?

Depending on the host system, the command line prompt changes in a container. It then starts with the emoji of a small box, followed by the name of the container. If this does not happen or you want to be absolutely sure, the shell command echo $CONTAINER_ID will help. Within a container, it returns its name, otherwise you will receive an empty line. Shell scripts can also use the environment variable $CONTAINER_ID to determine quite elegantly whether and if so, in which container they are currently running. In addition, there is the variable $container, in which Distrobox stores the name of the container service such as podman. This variable also only exists within the container.

Set up port forwarding

I have started a web server in my container. How do I reach it from the network? Do I have to set up port forwarding for this?

Services running in the container automatically behave as if you had started them directly on the host system. Consequently, all network clients can reach the web server via its IP address, unless a firewall prevents this. As the container also uses the host system's network, you do not need to pass or forward any ports to the container.

The situation is different if the container is locked into its own network environment via the --unshare-netns parameter. In this case, you must set up port forwarding. Distrobox itself does not offer a separate option for this, but passes the required parameter to the container services running in the background via the -a switch when the container is created:

distrobox create --unshare-netns -a "-p 8080:8000" -i ubuntu -n ubuntu-nonet

With "-p 8080:8000", all requests that hit port 8080 of the host system land directly in the container at port 8000. If the host has the IP address 192.168.1.101, the web server then listens at http://192.168.1.101:8080. You add further ports using the same scheme in the quotation marks: for example, -a "-p 8080:8000 -p 443:9000" also sets up forwarding for all requests at port 443 to port 9000 in the container.

Updating distributions

How do I automatically keep the distributions in the containers up to date?

The distrobox upgrade --all command updates all containers at once. You only need to start it regularly, for example via cron or a systemd timer. For the latter, you need suitable units. Examples of two simple systemd units are available for download. The timer distrobox-upgrade.timer then uses the service unit distrobox-upgrade.service to start an upgrade one hour after the host system boots and then once a day. Copy both units to ~/.config/systemd/user/ and activate them with the following command:

systemctl --user enable --now distrobox-upgrade.timer

Container with root rights

I would like to record the network traffic in my container using tcpdump. Even if I call the tool with sudo, I only get an error message. Allegedly I do not have the necessary rights. How can that be?

If the Podman recommended by us is used as a container manager, Distrobox starts the container under your user account. Within the container, you can call programs with sudo and thus system administrator rights, but the application continues to run under your user account –, which is usually prohibited from listening to the network interface or executing the corresponding socket action. This behavior is intentional for security reasons. If you want to throw this to the wind and run programs with comprehensive rights, add the parameter --root when creating and entering the container. Programs started in the container with sudo then run like the container with root rights and can, among other things, record network traffic without any restrictions, but can also do everything else that root is allowed to do.

Create backups

I have set up a development environment in a container that I would now like to back up and transfer to my laptop. Is that possible?

Distrobox itself cannot create backups or transfer them to other systems. This is only possible with the container managers used under the hood. Caution: The procedure described below only backs up the container itself. All other data, such as the documents and configuration files from your home directory, must be backed up separately.

To back up the container ubuntu-ct, first stop it with distrobox stop ubuntu-ct. Then create an image from the container

podman container commit -p ubuntu-ct ubuntu-image

If it is running under Docker, replace podman with docker. The command creates an image from the container with the name ubuntu-image. Then export the image to a file:

podman save -o ubuntu-image.tar ubuntu-image:latest

The command then writes the image to the tar archive ubuntu-image.tar.

To restore the container, import it as an image with load and create a new container:

podman load -i ubuntu-image.tar
distrobox create -i ubuntu-image:latest -n ubuntu-ct

This command combination is also suitable for creating container blueprints if you want to start several similar services.

(nen)