docker — detailed usage

A compact Go-based utility that demonstrates simple container-like behavior using Linux namespaces, cgroups and a bundled minimal root filesystem in ubuntufs/.

This README documents how the project works (using main.go and utils.go), how to build and run the program, and safe example workflows for inspecting or packaging the provided ubuntufs/ tree.

Files of interest

• main.go — the CLI and namespace/container orchestration logic
• utils.go — helpers that create cgroups, set limits and hostname
• Makefile — convenience target for building and launching a container-like process
• ubuntufs/ — the minimal Ubuntu-like rootfs included in the repo

High-level behavior

• main.go supports two process modes selected via the --ProcessType flag:
  • --ProcessType=run starts a parent process that re-executes the current binary with --ProcessType=child inside new namespaces.
  • --ProcessType=child runs inside the new namespaces and performs chroot("ubuntufs/"), mounts /proc, applies cgroup limits and then runs the requested command.
• utils.go creates a cgroup directory under /sys/fs/cgroup/<containerName> and writes to pids.max and memory.max to enforce limits.

Prerequisites & safety

• Go 1.20+ (or a compatible Go toolchain)
• Linux host with namespace and cgroup support. The code writes to /sys/fs/cgroup/* and expects writable cgroup controllers (common with cgroup v2 or properly mounted controllers).
• Root privileges are required for namespace creation, mounting, chroot, and writing cgroup limits. Run the examples with sudo or from an account with the necessary capabilities.
• This project is educational; do not use it to run untrusted code on production hosts.

Build

Build the binary with either the Makefile or go build:

go build -o main ./

Or use the Makefile target:

make run

The make run target builds and then executes the binary using sudo with the following example flags defined in the Makefile:

• --ProcessType=run — start the parent which spawns the namespaced child
• --name=container — container name used for the cgroup path
• --processes=20 — sets pids.max for the cgroup
• --memory=10485760 — sets memory.max for the cgroup (value in bytes)

Run (manual)

You can run the parent process directly; it will spawn a child process in new namespaces and then run the provided command inside the ubuntufs/ chroot. Example (uses sudo):

sudo ./main --ProcessType=run --name=mycontainer --processes=10 --memory=52428800 /bin/bash

This will:

1. The parent process will re-exec /proc/self/exe with --ProcessType=child and clone flags: CLONE_NEWUTS, CLONE_NEWPID, CLONE_NEWNS, CLONE_NEWNET, CLONE_NEWIPC.
2. The child will:
   • create /sys/fs/cgroup/<containerName> and write its PID to cgroup.procs.
   • write limits to pids.max and memory.max under that cgroup path.
   • call syscall.Chroot("ubuntufs/") and syscall.Chdir("/").
   • mount proc at /proc and then exec the requested command (e.g., /bin/bash).

Example output

When running the child you should see a line similar to:

Running with pid 12345

And then the shell or command prompt inside the chroot.

Notes on ubuntufs/

• ubuntufs/ is an expanded root filesystem tree (not an image file). You can inspect it directly or use it as a chroot target as the program does.
• To add binaries, libraries or configuration, copy files into the appropriate directories inside ubuntufs/ (for example add /bin/sh and its required libraries into ubuntufs/bin and ubuntufs/lib respectively).

Security & limitations

• This program does not perform full container isolation (no seccomp, no user namespaces, no sophisticated filesystem layering).
• Limitations depend on host kernel configuration and cgroup setup; test on a disposable VM if possible.

Contributing

• For code changes, update main.go or utils.go and add small focused commits. Add unit tests where appropriate.
• If you want, I can add a --help implementation in main.go that prints usage and available flags, or provide a sample Dockerfile that demonstrates how to incorporate ubuntufs/ into a Docker context.

License

• No license file is included. Add a LICENSE if you plan to publish this repository.

---