Repository files navigation

The cultured host's toolkit for ill-mannered Linux guests.

This package provides basic containerization tools for running Linux guests on a variety of platforms.As of the time of writing, it supports two execution backends:

• A Linux User Namespaces executor, which is very fast and lightweight

• ADocker (orPodman) executor which is slower, but more compatible (it works on macOS, and may work on Windows)

The executors are responsible for running/virtualizing a givenCmd within a root filesystem that is defined by the user, along with various paths that can be mounted within the sandbox.These capabilities were originally built forBinaryBuilder.jl, however this functionality is now mature enough that it may be useful elsewhere.

To make use of this toolkit, you will need to have a root filesystem image that you want to use.This package can download a minimal Debian rootfs that can be used for quick tests; to launch/bin/bash in an interactive shell run the following:

using Sandboxconfig=SandboxConfig(Dict("/"=> Sandbox.debian_rootfs());stdin,stdout,stderr,)with_executor()do exerun(exe, config,`/bin/bash -l`)end

While this launches an interactive session due to hooking upstdout/stdin, one can easily capture output by settingstdout to anIOBuffer, or even aPipeBuffer to chain together multiple processes from different sandboxes.

To use more interesting rootfs images, you can either create your own using tools such asdebootstrap or you can pull one from docker by using thepull_docker_image() function defined within this package. See thecontrib directory for examples of both.

You can also check out the latest releases of theJuliaCI/rootfs-images repository, which curates a collection of rootfs images for use in CI workloads.

Sandbox contains facilities for automatically registeringqemu-user-static interpreters withbinfmt_misc to support running on multiple architectures.As of the time of this writing, this is only supported on when running on a Linux host with thex86_64,aarch64 orpowerpc64le host architectures.The target architectures supported arex86_64,i686,aarch64,armv7l andpowerpc64le.Note that whileqemu-user-static is a marvel of modern engineering, it does still impose some performance penalties, and there may be occasional bugs that break emulation faithfulness.

For example, to run an aarch64 (ARM v8):

using Base.BinaryPlatforms, Sandbox# We'll run for this platformaarch64=Platform("aarch64","linux")config=SandboxConfig(# Map in a rootfs mounted at `/` that is DebianDict("/"=> Sandbox.debian_rootfs(;platform=aarch64));# Run using qemu-user-static/binfmt-misc    multiarch=[aarch64],# Hook up stdout/stderr/stdin so we can be interactivestdout,stderr,stdin,# This works around some problems with cross-device links# when installing things via `apt`    persist=true)with_executor()do exerun(exe, config,`/bin/bash -l`)end