OS Jackfruit – Mini Container Runtime with Kernel Memory Monitor

Overview

This project implements a lightweight container runtime and kernel-level memory monitor for Linux.

It supports:

• launching isolated containers using Linux namespaces
• supervising multiple containers concurrently
• logging per-container output
• tracking container memory usage in kernel space
• enforcing soft and hard RSS memory limits

---

Architecture

System consists of two major components:

1. User-space Runtime (engine.c)

Responsible for:

• supervisor daemon
• container creation using clone()
• namespace isolation:
  • PID namespace
  • UTS namespace
  • mount namespace
• control-plane IPC via UNIX domain sockets
• log collection and storage
• communication with kernel monitor via ioctl

2. Kernel-space Monitor (monitor.c)

Responsible for:

• maintaining tracked container PID list
• periodic RSS scanning using kernel timer
• soft-limit warning generation
• hard-limit process termination
• cleanup on process exit/unregister

---

IPC Design

Control Plane IPC: UNIX Domain Socket

Used between:

• CLI commands (start, stop, ps, logs)
• supervisor daemon

Chosen because:

• reliable local IPC
• bidirectional communication
• simple request/response design

Kernel IPC: ioctl()

Used between:

• supervisor
• /dev/container_monitor

Chosen because:

• direct structured communication with kernel module
• efficient registration/unregistration interface

---

Memory Monitoring Behavior

Each container is registered with:

• soft memory limit
• hard memory limit

Soft Limit:

When exceeded:

• warning logged once

Example: SOFT LIMIT container=hog pid=8434 rss=42598400 limit=41943040

Hard Limit:

When exceeded:

• process killed using SIGKILL
• removed from monitor list

Example: HARD LIMIT container=hog pid=8434 rss=67764224 limit=67108864

---

Locking Choice Justification

A mutex protects the monitored linked list.

Reason:

• ioctl handlers may sleep
• timer callback logic may call functions that sleep
• spinlocks unsuitable for sleeping code paths

Thus mutex is safer and simpler.

---

Kernel Data Structure

Kernel module uses:

• linked list of monitored entries

Each entry stores:

• PID
• container ID
• soft limit
• hard limit
• soft warning emitted flag

---

Test Procedure

Build:

make

Load kernel module:

sudo insmod monitor.ko

Start supervisor:

sudo ./engine supervisor ./rootfs-base

Start memory test container:

sudo ./engine start hog ./rootfs-alpha /memory_hog

Watch kernel logs:

sudo dmesg -w

Verified Functionality

Successfully verified:

• container launch
• container stop
• process listing
• log retrieval
• kernel registration
• soft memory warning
• hard memory kill enforcement

Example Successful Output

[container_monitor] Registering container=hog pid=8434 soft=41943040 hard=67108864
[container_monitor] SOFT LIMIT container=hog pid=8434 rss=42598400 limit=41943040
[container_monitor] HARD LIMIT container=hog pid=8434 rss=67764224 limit=67108864

Files Included

• engine.c
• monitor.c
• monitor_ioctl.h
• Makefile
• README.md