Sysbox Documentation

Sysbox is an open-source container runtime (a specialized runc) that enhances container isolation and enables containers to run system-level workloads typically reserved for VMs.

Key Capabilities:

• Improved Isolation: Uses Linux user-namespaces so the container's root user has zero privileges on the host. It virtualizes portions of procfs and sysfs and hides host information.
• System Workloads: Allows running software like systemd, Docker, Kubernetes, K3s, and buildx inside containers without modification, special images, or privileged mode.
• VM-like Environment: Provides a VM-like experience without the overhead of actual VMs or the need for nested virtualization in cloud environments.
• Coexistence: Can run side-by-side with other runtimes like the default runc or Kata.

Sysbox system containers provide enhanced isolation by always using all Linux namespaces. Unlike standard Docker containers (which rely on the container manager to choose namespaces), Sysbox automatically enables all namespaces, including cgroup and user namespaces, to ensure stronger isolation.

Namespace Comparison:

When using nested container environments (like running Docker inside a system container), Sysbox uses specific terminology to avoid confusion:

• Outer Container: The system container created at the host level, launched using Docker and Sysbox.
• Inner Container: The application container created within the outer container (e.g., a container managed by the Docker or Kubernetes instance running inside the system container).

Sysbox documentation is organized into several specialized guides depending on your needs:

• Installation: Follow the Sysbox Installation guide to set up the tool.
• Usage and Features: Refer to the Sysbox User Guide for detailed information on installation, features, and functionality.
• Compatibility: Check the Sysbox Distro Compatibility doc to ensure your distribution is supported.
• Development: Use the Sysbox Developers Guide if you want to build Sysbox from source or contribute to the project.

Sysbox consists of three main components that work together to provide system containers. Users typically interact with these via higher-level tools like Docker or containerd rather than directly.

• sysbox-runc: The container runtime (front-end) that performs low-level kernel setup. It is invoked by Docker/containerd to launch containers.
• sysbox-fs: A FUSE daemon (back-end) that emulates portions of procfs and sysfs to make the container resemble a virtual host while maintaining isolation.
• sysbox-mgr: A daemon (back-end) that manages user-ID/group-ID mappings and special mounts. Communication between components occurs via gRPC.

To run Sysbox, your Linux host must meet these requirements:

1. Use a supported Linux distribution (e.g., Ubuntu, Debian, or Flatcar for shiftfs support).
2. Use systemd as the host's process manager.

Sysbox performs partial virtualization of procfs and sysfs to allow system containers to function like real machines while protecting the host.

• Procfs Virtualization: Exposes /proc as read-write so container processes can interact with it, but prevents them from modifying system-wide host settings. This virtualization is independent for each system container and extends to any inner containers.
• Sysfs Virtualization: Protects host settings via sysfs. Additionally, /sys/fs/cgroup is mounted read-write to allow container processes to manage a subset of cgroup resources assigned to the container itself.