3.2. Using Pre-Built Docker Images#

SimBricks provides pre-built Docker images on Docker Hub. Since the move to conda packaging, there are exactly three images, building on each other:

  • simbricks/simbricks-baseenv — Ubuntu base environment with micromamba installed and the SimBricks conda channel pre-configured. Use this as a starting point for custom environments: any SimBricks package is a micromamba install away.

  • simbricks/simbricks-runner — base environment plus the simbricks-runner package. Runs a Main Runner that connects to the SimBricks Backend (entrypoint run_runner.sh, see Running Your Own Runner).

  • simbricks/simbricks-executor — runner image plus the standard simulator packages (QEMU, gem5, ns-3, FEMU, i40e, e1000, and the basic net/mem simulators) and the tooling to build disk images (libguestfs, packer, qemu-img). This is the image that actually executes simulations, either spawned by a Runner’s Docker plugin or used directly. It ships no disk image of its own: the images SimBricks publishes are downloaded when a run first uses one (see The images SimBricks publishes), so the container needs network access to https://disk-images.simbricks.io, and an image cache (Reusing builds across runs) is worth mounting so that download is paid once.

For a quick interactive environment with all standard simulators available, you can enter the executor image directly:

docker run --rm -it --device /dev/kvm --entrypoint /bin/bash simbricks/simbricks-executor

3.2.1. Requirements on the host#

KVM for fast QEMU simulations. For QEMU’s fast functional mode, the container needs access to the KVM device, enabled with --device /dev/kvm (check that /dev/kvm exists on your host — on machines without virtualization support or VMs without nested virtualization you can still run QEMU, just slower via TCG).

perf event access for gem5. gem5 requires the Linux perf_event_paranoid setting to be 1 or lower. Since this is a kernel setting, it can only be changed from a privileged container (or directly on the host):

docker run --rm -it --device /dev/kvm --privileged --entrypoint /bin/bash simbricks/simbricks-executor
# inside the container:
sudo sysctl -w kernel.perf_event_paranoid=1

Raw images for gem5. The images SimBricks publishes are qcow2, and gem5 requires raw. Build a layered image on top of one in your script (Building an image from the script) — the build produces raw and extracts the boot artifacts gem5 needs. For an image of your own placed under GLOBAL_INPUT_DIR, the executor’s default entrypoint converts each images/<name>/<name> to .raw on startup; when entering the container manually you can do it yourself:

qemu-img convert -f qcow2 -O raw -S 4k \
    /global_input/images/my-image/my-image /global_input/images/my-image/my-image.raw