Install debugging tools

You can use common debugging tools like tcpdump or strace with Toolbox. Using the filesystem of a specified Docker container Toolbox will launch a container with full system privileges including access to system PIDs, network interfaces and other global information. Inside of the toolbox, the machine's filesystem is mounted to /media/root.

Quick debugging

By default, Toolbox uses the stock Fedora Docker container. To start using it, simply run:


You're now in the namespace of Fedora and can install any software you'd like via dnf. For example, if you'd like to use tcpdump:

[root@srv-3qy0p ~]# dnf -y install tcpdump
[root@srv-3qy0p ~]# tcpdump -i ens3
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on ens3, link-type EN10MB (Ethernet), capture size 65535 bytes

Specify a custom Docker image

Create a .toolboxrc in the user's home folder to use a specific Docker image:

$ cat .toolboxrc
$ /usr/bin/toolbox
Pulling repository

You can also specify this in a Container Linux Config:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.
# This config is meant to be consumed by the config transpiler, which will
# generate the corresponding Ignition config. Do not pass this config directly
# to instances of Container Linux.

    - path: /home/core/.toolboxrc
      filesystem: root
      mode: 0644
        inline: |

This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
  "ignition": {
    "config": {},
    "timeouts": {},
    "version": "2.1.0"
  "networkd": {},
  "passwd": {},
  "storage": {
    "files": [
        "filesystem": "root",
        "group": {},
        "path": "/home/core/.toolboxrc",
        "user": {},
        "contents": {
          "source": "data:,",
          "verification": {}
        "mode": 420
  "systemd": {}

Under the hood

Behind the scenes, toolbox downloads, prepares and exports the container image you specify (or the default fedora image), then creates a container from that extracted image by calling systemd-nspawn. The exported image is retained in /var/lib/toolbox/[username]-[image name]-[image tag], e.g. the default image run by the core user is at /var/lib/toolbox/core-fedora-latest.

This means two important things:

  • Changes made inside the container will persist between sessions
  • The container filesystem will take up space on disk (a few hundred MiB for the default fedora container)

SSH directly into a toolbox

Advanced users can SSH directly into a toolbox by setting up an /etc/passwd entry:

useradd bob -m -p '*' -s /usr/bin/toolbox -U -G sudo,docker,rkt

To test, SSH as bob:


   ______                ____  _____
  / ____/___  ________  / __ \/ ___/
 / /   / __ \/ ___/ _ \/ / / /\__ \
/ /___/ /_/ / /  /  __/ /_/ /___/ /
\____/\____/_/   \___/\____//____/
[root@srv-3qy0p ~]# dnf -y install emacs-nox
[root@srv-3qy0p ~]# emacs /media/root/etc/systemd/system/newapp.service