BCE - Bash Container Engine

BCE is a lightweight, educational container runtime written entirely in Bash (<200 lines). It demonstrates the core Linux primitives behind modern containers: namespaces, cgroups v2, and overlay filesystems (simulated via bind mounts).

Features

• Isolation: Uses unshare to create new PID, Mount, Network, and IPC namespaces.
• Resource Control: Implements Cgroups v2 logic to limit memory usage (default: 512MB).
• Filesystem: true root isolation via pivot_root (not just chroot).
• Networking: Sets up a veth pair connected to a host bridge (br0).
• Zero Dependencies: Requires only standard Linux utilities (util-linux, iproute2, coreutils).

Requirements

• Linux Kernel ≥ 4.19 (with Cgroup v2 enabled)
• Root privileges (for unshare, mount, ip, cgroups)
• xxd (usually in vim-common or strictly xxd package)

Quick Start

1. Networking Setup

BCE expects a bridge named br0 on the host to provide connectivity.

# strictly for testing; persistent config varies by distro
sudo ip link add br0 type bridge
sudo ip link set br0 up
sudo ip addr add 10.0.0.1/24 dev br0
# enable forwarding if you want internet access
# sudo sysctl -w net.ipv4.ip_forward=1

2. Prepare a RootFS

You need a directory containing a Linux filesystem.

mkdir -p /tmp/alpine-rootfs
# Download and extract a mini rootfs (example)
curl -o rootfs.tar.gz https://dl-cdn.alpinelinux.org/alpine/v3.18/releases/x86_64/alpine-minirootfs-3.18.3-x86_64.tar.gz
tar -xzf rootfs.tar.gz -C /tmp/alpine-rootfs

3. Run a Container

sudo ./bce run /tmp/alpine-rootfs /bin/sh
# Inside:
# / # ip addr
# / # mount

4. Manage Containers

# List active containers
sudo ./bce list

# Cleanup specific container
sudo ./bce clean <container_id>

# Cleanup all containers
sudo ./bce clean

Architecture

+-------------------+----------------+
|       HOST        |   CONTAINER    |
+-------------------+----------------+
|                   |                |
|  [ br0 ] <=====> [ veth ] (eth0)   |  <-- Configured via `ip link set netns`
| 10.0.0.1          | 10.0.0.2       |
|                   |                |
+-------------------+----------------+
|      PID 1        |     PID 2      |  <-- Forked process
+-------------------+----------------+
| Mnt Namespace     | Mnt Namespace  |  <-- `unshare --mount` + `pivot_root`
| (Host Root FS)    | (Root FS)      |
+-------------------+----------------+
| Cgroup v2         | Cgroup v2      |  <-- `/sys/fs/cgroup/bce-<id>`
| (Unlimited)       | (512MB RAM)    |
+-------------------+----------------+

The bce script performs the following steps:

1. ID Generation: Assigns a random hex ID.
2. Cgroup Setup: Creates /sys/fs/cgroup/bce-<id> and sets memory.max.
3. Process Isolation: unshare --pid --mount --net --fork into a child process.
4. Network Plumbing: Creates a veth pair, moving one end into the child namespace.
5. Root Switch: mount --bind -> pivot_root -> umount old_root for a clean mount namespace.
6. Teardown: On exit (or clean), removes the cgroup and network interfaces.

License

MIT