📦 A command-line utility (non-daemon) written in Go for creating Linux containers and sandboxing processes.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
James Mills 50ffc525a1
Add report calling to logger
5 days ago
.chglog Fix import paths 1 year ago
.vscode Refactor PortMapping to use nftabels 3 weeks ago
archive Initial Commit 2 years ago
cgroups Add e2e cli integration test suite (#31) 7 days ago
cli Add report calling to logger 5 days ago
cmd/box Add e2e cli integration test suite (#31) 7 days ago
container Refactor cgroups with proper cgroup v2 hiarchy (#26) 1 week ago
dns Add support for bind mounts and inject host /etc/resolv.conf into containers 2 years ago
docs Add screenshot to README 2 weeks ago
filesystem Fix Mount() 2 weeks ago
image Fix import paths 1 year ago
internal Refactor the init process 1 week ago
ipam Add doctor command for self-diagnosis 1 week ago
nat Add doctor command for self-diagnosis 1 week ago
network Fix a bug found on some SystemD systems like Ubuntu 22.04 (Thanks @markwylde) 1 week ago
reexec Initial Commit 2 years ago
tests Add pull tests 7 days ago
tools Fix GoReleaer conig 2 weeks ago
utils Refactor cgroups with proper cgroup v2 hiarchy (#26) 1 week ago
.DS_Store Refactor cgroups with proper cgroup v2 hiarchy (#26) 1 week ago
.drone.yml Add e2e cli integration test suite (#31) 7 days ago
.gitignore Fix .gitignore to ignore coverage files 7 days ago
.goreleaser.yml Fix GoReleaser config 1 week ago
CHANGELOG.md Update CHANGELOG for 0.0.10 1 week ago
LICENSE Initial Commit 2 years ago
Makefile Add e2e cli integration test suite (#31) 7 days ago
README.md Add screenshot to README 2 weeks ago
go.mod Add e2e cli integration test suite (#31) 7 days ago
go.sum Add e2e cli integration test suite (#31) 7 days ago
preflight.sh Add e2e cli integration test suite (#31) 7 days ago

README.md

box -- Containers in a Box

Build Status Go Report Card Go Reference

box is a command-lint utility (non-daemon) written in Go for creating Linux containers and sandboxing processes. box is basically a tiny version of docker, it uses neither containerd nor runc. box only implements a sub-set of features you may be used to coming from Docker or similar.

Screenshot

Features

box supports:

  • Control Groups for resource restriction (CPU, Memory, Swap, PIDs)
  • Namespace for global system resources isolation (Mount, UTS, Network, IPS, PID)
  • Union File System for branches to be overlaid in a single coherent file system. (OverlayFS)
  • Isolated Networking each container get its own networking and ip address automatically (IPAM)
  • Pulling OCI images from the Docker Hub
  • Builtin basic Networking and IPAM
  • and not much else...

Install

If you have a Go development environment setup with $GOPATH/bin/ in your $PATH the following will just work™ 😀

go get -u git.mills.io/prologic/box

Otherwise you can build from source using git (You still need the Go compiler):

git clone https://git.mills.io/prologic/box.git
cd box
make

Pre-built Binaries

There are pre-built binaries I publish regularly to the Releases page you can download and install. Example:

wget https://git.mills.io/prologic/box/releases/download/0.0.4/box_0.0.4_linux_amd64.tar.gz
tar xvf box_0.0.4_linux_amd64.tar.gz

Running rootless

Since box requires elevated privileges in order to create new namespaces and control groups, it must be run as root or with an effective uid of 0.

You can either run box as root, or you can install the binary with the suid bit set:

chmod u+s box

Usage

# box --help
A tiny tool for managing containers and sandbox processes

Usage:
  box [command]

Available Commands:
  exec        Run a command inside a existing Container.
  help        Help about any command
  images      List local images
  ps          List Containers
  pull        Pulls an OCI compatible image from a registry
  rm          Removes a Container.
  run         Run a command inside a new Container.
  stop        Stops a Container.
  version     Display the version of box and exit

Flags:
  -D, --debug   Enable debug logging
  -h, --help    help for box

Use "box [command] --help" for more information about a command.

Examples

Run /bin/sh in alpine:latest

box run alpine /bin/sh
box run alpine # same as above due to alpine default command

Run /bin/ch -c 'echo "Hwllo World"':

box run alpine -- /bin/sh -c 'echo "Hello World"'

NOTE: The -- is important here as this acts as the "flag terminator" for the box CLI and the run sub-command and allows you to then use command-line options that are passed to your images' entrypoint.

Networking

IP Address Management (IPAM)

Currently box has a builtin IPAM (IP Address Management) that has a hard coded subnet of 172.30.0.0/16. A box0 bridge (switch) is setup for all containers (automatically) and containers are put into their own isolated Network Namespace and assigned an IP Address out of this subnet automatically (without requiring DHCP).

Currently there is no support for using a different subnet or assigning static IP Addresses to containers at this time.

External Networking and Port Mapping

box uses nftables to create and manipulate NAT rules to allow containers access to external networks (MASQUERADE) and mapping ports from the host to the container (DNAT).

DNS Resolvers

box injects the host's /etc/resolv.conf into a newly formed container so as long as DNS Resolution works on your host, it will work inside containers too.

Notes

box is/does NOT:

  • designed to be minimal and lightweight.
  • designed to be used in critical production workloads (yet).
  • have any orchestrator(s) for managing services.
  • have any multi-host or clustering support of any kind.
  • have any support for volumes besides bind-mount(s) from the host
  • have any other features you'd expect from Docker, Docker Swarm or Kubernetes.

License

box is licensed under the MIT License.