What is rustjail? Core Container Runtime Primitives for CubeSandbox

rustjail is an internal Rust library that implements OCI-compatible container runtime primitives, providing namespace isolation, cgroup management, process lifecycle control, and seccomp filtering for the CubeSandbox micro-VM architecture.

rustjail serves as the low-level container engine powering TencentCloud's CubeSandbox project. Defined as a workspace member in agent/Cargo.toml, this crate supplies the essential mechanisms to create, constrain, and manage lightweight Linux containers that isolate guest workloads according to the Open Container Initiative (OCI) specification.

Container Isolation and Namespace Management

The foundation of rustjail's architecture rests on Linux kernel namespaces, implemented through the LinuxContainer abstraction.

LinuxContainer and Namespace Creation

In agent/rustjail/src/container.rs, the LinuxContainer struct implements the BaseContainer trait to orchestrate namespace creation. When instantiated via LinuxContainer::new(), it establishes new PID, mount, network, IPC, UTS, and user namespaces for each sandbox, ensuring complete process and filesystem isolation from the host.

use rustjail::container::{BaseContainer, LinuxContainer};
use rustjail::specconv::CreateOpts;

let opts = CreateOpts {
    spec: oci_spec,
    // rootfs path, mounts, etc.
};
let container = LinuxContainer::new(opts)?;
let pid = container.start()?; // Returns the PID of the container init

The container lifecycle also includes synchronization primitives such as rustjail::sync and rustjail::sync_with_async to coordinate multi-threaded startup sequences, ensuring namespaces are fully established before the init process executes.

Resource Control and Cgroup Management

Rustjail enforces resource constraints through the Linux cgroup subsystem, exposed via the rustjail::cgroups modules.

Cgroup Configuration and Monitoring

The agent/rustjail/src/cgroups/ directory contains filesystem-based helpers that create and configure cpu, memory, cpuset, and blk-io control groups. These modules provide functions to set limits and monitor out-of-memory (OOM) conditions through event notifiers.

use rustjail::cgroups::fs;

// Set a 256 MiB memory limit
fs::set_memory_limit("my_container", 256 * 1024 * 1024)?;

// Retrieve guest CPU set topology
let guest_cpuset = rustjail_cgroups::fs::get_guest_cpuset()?;

As shown in agent/src/sandbox.rs, the higher-level agent code leverages these primitives to apply hardware topology and resource limits to micro-VMs.

Process Management and I/O Streams

Managing the container init process and its standard I/O requires careful handling of file descriptors and process state.

Process Spawning and Pipe Streams

The rustjail::process::Process struct in agent/rustjail/src/process.rs handles the execution of the container's init process, including capability configuration and seccomp setup. For I/O redirection, rustjail::pipestream::PipeStream in agent/rustjail/src/pipestream.rs provides async-compatible channels that connect the host's stdin/stdout/stderr to the containerized process.

use rustjail::process::Process;
use rustjail::pipestream::PipeStream;

// Start the init process inside isolated namespaces
let pid = container.start()?;

// Attach pipe streams for I/O
let streams = PipeStream::new(pid)?;

The library also implements WAIT_PID_LOCKER for signal-safe process reaping and supports exec-style re-entry for running additional commands within existing containers.

OCI Specification and gRPC Conversion

Rustjail bridges the gap between CubeSandbox's gRPC API and standard OCI runtime specifications.

specconv and gRPC Translation

The rustjail::specconv module in agent/rustjail/src/specconv.rs converts gRPC-encoded OCI specifications (received via CubeAPI) into the oci crate structures used internally. This includes translating process definitions, mounts, and resource limits from the wire format to runtime configurations.

// Convert gRPC spec to OCI spec
let oci_process = rustjail::process_grpc_to_oci(&grpc_spec.process);

This conversion ensures that container definitions arriving through the RPC interface in agent/src/rpc.rs are validated and normalized before container creation.

Security: Seccomp and Mount Validation

Security features in rustjail are exposed through optional Cargo features defined in agent/rustjail/Cargo.toml.

Seccomp BPF Filtering

When the seccomp feature is enabled, rustjail::seccomp generates and loads Berkeley Packet Filter (BPF) programs to restrict available system calls. This generates allow-lists or deny-lists that the kernel enforces before executing syscalls in the container context.

# In Cargo.toml

[features]
seccomp = ["rustjail/seccomp"]

#[cfg(feature = "seccomp")]
use rustjail::seccomp::Seccomp;

// Create a filter allowing only read/write syscalls
let filter = Seccomp::new(vec!["read", "write"])?;
filter.apply()?; // Loads into the kernel for the current thread

Mount Handling

The rustjail::mount module performs bind-mounts, overlay filesystem mounts, and validates mount options before application, preventing dangerous configurations like unrestricted host filesystem access.

Summary

• rustjail is a Rust workspace member in agent/Cargo.toml that implements OCI-compatible container runtime primitives for CubeSandbox.
• LinuxContainer in agent/rustjail/src/container.rs creates PID, mount, network, and user namespaces for isolation.
• rustjail::cgroups modules enforce resource limits on CPU, memory, and I/O while monitoring OOM events.
• PipeStream and Process manage container init lifecycle and async I/O redirection between host and guest.
• specconv translates gRPC OCI specifications from CubeAPI into internal runtime structures.
• Optional seccomp support generates BPF filters to restrict system calls, enhancing security.

Frequently Asked Questions

What is rustjail and how does it relate to CubeSandbox?

rustjail is an internal Rust library within the TencentCloud/CubeSandbox repository that implements the core container runtime. It provides the low-level primitives—namespace creation, cgroup management, and process control—that the CubeSandbox agent uses to isolate micro-VM workloads. It is bundled as a workspace crate in agent/Cargo.toml and consumed by the main agent code in agent/src/sandbox.rs.

Which Linux namespaces does rustjail create for each container?

According to the source code in agent/rustjail/src/container.rs, rustjail creates new PID, mount, network, IPC, UTS, and user namespaces for each LinuxContainer instance. This comprehensive isolation ensures that processes, network interfaces, and filesystem views remain separate from the host and other containers.

How does rustjail handle OCI specification conversion?

The rustjail::specconv module in agent/rustjail/src/specconv.rs provides conversion functions like process_grpc_to_oci that translate gRPC-encoded OCI specifications (defined in the protocols::oci module) into the standard oci crate structures used by the runtime. This bridge allows CubeSandbox's API to accept container definitions while maintaining OCI runtime compatibility.

Is seccomp support mandatory when using rustjail?

No, seccomp support is optional and controlled via Cargo features in agent/rustjail/Cargo.toml. The seccomp feature must be explicitly enabled to include the rustjail::seccomp module and its BPF filtering capabilities. When disabled, rustjail operates without system call filtering, relying on other security mechanisms like capabilities and namespaces for isolation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}