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 a pre-built base disk image at /global_input/images/base/ (built with image-builder, including the gem5-compatible kernel, the m5 tool, and the Corundum mqnic driver). This is the image that actually executes simulations, either spawned by a Runner’s Docker plugin or used directly.

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 shipped base image is in qcow2 format. gem5 requires raw images; the executor’s default entrypoint converts the image on startup, but when entering the container manually you can convert it yourself:

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