Building Containers from Scratch in Rust

Internals, Linux Kernel Primitives and Container Runtime Engineering

Introduction

Chapter 1: What Are Containers Really

1. The Process as the Fundamental Unit
2. Chroot and the Birth of Isolation Ideas
3. From Zones to Linux Containers to Docker
4. How a Container Runtime Actually Works
5. Containers vs Virtual Machines vs Sandboxes
6. What This Book Will Build

Chapter 2: Rust for Systems Programming

1. Why Rust for Container Runtimes
2. Tooling: Cargo, rustup, Cross-compilation, musl
3. Error Handling Patterns for Systems Code
4. The unsafe Boundary: When and How
5. Linux FFI with libc and bindgen
6. Async vs Sync in Runtime Code
7. Structuring a Systems Library in Rust

Chapter 3: Linux Kernel Prerequisites

1. Minimum and Recommended Kernel Versions
2. Required Kernel Configuration Options
3. Namespace Support and Detection
4. cgroup v1 vs v2: Distribution Defaults
5. Essential Tooling: strace, nsenter, lsns, bpftrace
6. Building and Testing on Different Distributions

Chapter 4: Linux Namespaces Overview

1. The Namespace Abstraction in the Kernel
2. How Namespaces Are Structured in Kernel Memory
3. The clone and unshare System Calls
4. Joining and Leaving Namespaces with setns
5. Inspecting Namespaces: /proc, nsenter, lsns
6. Namespace Hierarchy and Inheritance

Chapter 5: PID Namespaces and Process Isolation

1. How clone Works: Flags, Stack and Child Setup
2. fork, vfork, execve: The Process Creation Family
3. Nested PID Namespaces and PID Translation
4. PID 1: Signal Handling, Zombie Reaping, init Responsibilities
5. Signals Across Namespace Boundaries
6. Process Tracing and ptrace Interaction
7. Implementing Our First PID Namespace Container

Chapter 6: Mount Namespaces and Filesystem Isolation

1. The Mount Namespace Data Structures
2. chroot: History, Limitations and Security Gaps
3. pivot_root: How It Actually Works
4. Bind Mounts and Recursive Mounts
5. Mount Propagation: Shared, Private, Slave, Unbindable
6. Creating a Minimal Container Root Filesystem
7. /proc, /sys and Pseudo-filesystem Mounting
8. Integrating Mount Namespaces into Our Runtime

Chapter 7: User Namespaces and Privilege

1. The User Namespace Concept
2. UID and GID Mapping Mechanics
3. /proc/self/uid_map, gid_map and setgroups
4. Root Inside, Nobody Outside
5. The no_new_privs Flag and Privilege Escalation
6. Rootless Container Limitations and Workarounds
7. Multi-Level User Namespaces
8. Rust Implementation of User Namespace Setup

Chapter 8: Network Namespaces and Container Networking

1. Network Namespace Isolation
2. Virtual Ethernet (veth) Pairs
3. Linux Bridges and Layer 2 Forwarding
4. IP Addressing and Routing Inside Containers
5. NAT and Masquerading with iptables/nftables
6. DNS Resolution Configuration
7. Loopback Interface Requirements
8. Common Networking Topologies
9. Rust Implementation of Container Networking

Chapter 9: Completing the Namespace Set

1. IPC Namespaces: System V and POSIX IPC
2. UTS Namespace: Hostname and Domainname Isolation
3. Time Namespaces (kernel 5.6+): Clock Manipulation
4. cgroup Namespaces
5. When Each Namespace Is Necessary
6. Namespace Setup Order and Interactions
7. Rust Implementation of Full Namespace Setup

Chapter 10: Control Groups: Architecture and Evolution

1. The Control Group Concept
2. cgroup v1: Hierarchies, Controllers and Complexity
3. Why cgroup v2 Was Designed
4. The Unified Hierarchy
5. Controller Types and Delegation
6. Distribution Defaults and Detection

Chapter 11: cgroup v2 Deep Dive

1. Hierarchy Operations: Creating, Moving, Cleaning Up
2. Process Placement in cgroups
3. CPU Controller: weights, quotas, periods, scheduling
4. Memory Controller: limits, accounting, high thresholds
5. Swap Control and Memory+Swap Limits
6. OOM Killer Behavior and oom.kill_disable
7. I/O Controller: throttling, weights, cgroup2 io.stat
8. PID Controller: limiting process counts
9. Pressure Stall Information (PSI)
10. Device Controller: blocking and allowing devices
11. Rust Implementation of cgroup v2 Setup

Chapter 12: Linux Capabilities

1. The Problem with UID 0
2. Capability Sets: Permitted, Effective, Inheritable, etc.
3. Capability Inheritance Across execve and clone
4. prctl Controls: no_new_privs, dumpable, etc.
5. Ambient Capabilities (kernel 4.3+)
6. Common Capabilities Used in Containers
7. Implementing Capability Dropping

Chapter 13: Mandatory Access Control and System Call Filtering

1. System Call Filtering with seccomp
2. seccomp Modes: Strict, Filter, BPF
3. Writing seccomp Filters in Rust
4. The LSM Framework Architecture
5. AppArmor vs SELinux for Containers
6. Integrating MAC Policies into Our Runtime
7. seccomp Default Profiles for Containers

Chapter 14: Container Filesystems and OverlayFS

1. The Layered Image Concept
2. OverlayFS: How Copy-on-Write Works
3. Upperdir, Lowerdir, Workdir
4. Whiteouts and Opaque Directories
5. File Ownership and UID/GID in Images
6. Mounting an OverlayFS Root
7. Performance Characteristics and Limitations
8. Rust OverlayFS Integration

Chapter 15: Container Images, Manifests and Rootfs Assembly

1. Docker Image Format History
2. OCI Image Specification
3. Image Manifests and Config Blobs
4. Content-Addressable Storage
5. Image Extraction and Rootfs Assembly
6. Building a Minimal Image from Scratch
7. Integration with Our Runtime

Chapter 16: Project Architecture and Design

1. Runtime Requirements and Goals
2. Project Structure and Cargo Configuration
3. The Container Config Data Model
4. Component Responsibilities
5. Communication Between Parent and Child
6. Error Handling and Failure Recovery

Chapter 17: Implementing Namespace Setup

1. Namespace Config and Validation
2. unshare Implementation in Rust
3. setns and Namespace File Descriptors
4. Ordering of Namespace Operations
5. The Initial Process Entry Point
6. Testing Namespace Setup

Chapter 18: Implementing Filesystem Configuration

1. Mount Specification Parsing
2. pivot_root Implementation
3. Bind Mount Creation
4. Pseudo-filesystem Mounts
5. Mount Propagation Configuration
6. Cleanup on Failure

Chapter 19: Implementing Resource Control

1. cgroup v2 Setup: Hierarchy Creation and Process Placement
2. Controller Configuration from Spec
3. Capability Dropping Implementation
4. seccomp Filter Construction
5. Integration into the Startup Sequence

Chapter 20: Process Lifecycle Management

1. The Parent-Child Handshake Protocol
2. clone/fork + execve Sequence
3. File Descriptor Management
4. Signal Forwarding from Host to Container
5. Process State Monitoring
6. Container Shutdown and Cleanup
7. Zombie Handling and PID 1 Interaction

Chapter 21: Networking Integration

1. Network Config Specification
2. veth Pair Creation
3. Bridge Attachment and Routing
4. IP Address and DNS Configuration
5. Integration with Namespace Setup
6. Rootless Networking Options
7. DNS Configuration

Chapter 22: Rootless Containers

1. What Rootless Really Means
2. Required User Namespace Configuration
3. Rootless cgroup Delegation
4. Rootless Mount Namespaces and Privileged Mounts
5. Rootless Networking Limitations
6. Testing Rootless Execution

Chapter 23: OCI Runtime Specification Compliance

1. OCI Runtime Spec Overview
2. Bundle Layout and config.json
3. Where We Follow the Spec
4. Where We Simplify
5. Comparison with runc Architecture
6. Comparison with crun Implementation Choices
7. Path to Full Spec Compliance

Chapter 24: Security Analysis and Threat Modeling

1. The Container Security Promise and Its Limits
2. Threat Model: What Are We Defending Against
3. Namespace Escape Vulnerabilities
4. cgroup and Capability Abuse
5. seccomp and Kernel Exploits
6. Common Misconfigurations That Break Isolation
7. Defense-in-Depth Implementation
8. Safe Testing of Container Isolation

Chapter 25: Debugging, Observability and Production Readiness

1. Debugging with strace: Practical Examples
2. eBPF and bpftrace for Container Observability
3. Understanding Kernel Logs and dmesg
4. Performance Profiling with perf
5. Common Failure Modes and How to Fix Them
6. Hardening for Production Use
7. What We Did Not Implement (and Why)

Conclusion

References