Debugging with Toolbx

The FCOS image is kept minimal by design to reduce the image size and the attack surface. This means that it does not include every troubleshooting tools that a normal OS may include. Instead, the recommended approach is to leverage containers with the toolbox utility included in the image.

What is Toolbx?

Toolbx is a utility that allows you to create privileged containers meant to debug and troubleshoot your instance. It is a wrapper around podman which starts long running containers with default mounts and namespaces to facilitate debugging the host system.

Esses contêineres podem ser usados para instalar ferramentas que você pode precisar para troubleshooting.

Using Toolbx

You can create a new toolbox by running the command below. On the first run, this will ask you if you want to use the image registry.fedoraproject.org/fedora-toolbox:35.

criação de toolbox

You can then list all the running toolboxes running on the host. This should show you your newly created toolbox. In this case, it is named fedora-toolbox-35.

lista de toolboxes

As pointed out by the output of the toolbox create command, you can enter the following command to enter your toolbox.

toolbox enter

Agora que você está no contêiner, você pode usar o gerenciador de pacotes dnf incluso, para instalar pacotes. Por exemplo, vamos instalar strace para olhar a syscall feita pela ferramenta toolbox do host.

sudo dnf install strace
# Alguns diretórios hosts são montados em /run/host
strace -eread /run/host/usr/bin/toolbox list

Uma vez que tenha terminado o trabalho em seu contêiner, você pode sair dele e removê-lo do host com o seguinte comando.

toolbox rm --force fedora-toolbox-35

Toolbx allows you to create toolboxes with your custom images. You can find more details in the toolbox manpages.

Want to help? Learn how to contribute to Fedora Docs ›