muqiuhan / bonding

A Minimalism container implementation in C++

Bonding

A Minimalism container implementation in C++

Build from source

This project is built using xmake.

This is currently the only way to use bonding. Fortunately, xmake supports the generation of files required by build tools such as Ninja, CMake and Makefile, so this project supports building from Ninja or CMakes:

1. clone: git clone https://github.com/muqiuhan/bonding --recurse-submodules --depth=1
2. and build it: make build.release or build for debug: make build.debug

   or use one of cmake and ninja

Install

• The easiest is make install, it will try to request administrator permission to install

Other install options:

• xmake -o INSTALLDIR to set the install directory.

  e.g. xmake install -o /usr/local

  or DESTDIR=/usr/local xmake install

  or INSTALLDIR=/usr/local xmake install

• xmake -g GROUP to install all targets of the given group. It support path pattern matching.

  e.g. xmake install -g test

  or xmake install -g test_*

  or xmake install --group=benchmark/*

Debug

Bonding need advanced permissions to create, such as restricting resources through cgroups, restricting system calls through seccomp, etc. So they must be debug with sudo. For example:

sudo lldb ./build/linux/x86_64/debug/bonding run --debug

USAGE:

Usage: bonding [help] [init] [run] [help] [version]

 [init]
        Initialize the current directory as the container directory

 [run]
        Run with the current directory as the container directory

 [help]
        show this message

 [version]
        show the version of bonding

Bonding sets the environment and various parameters through the configuration file bonding.json:

{
    "hostname": "Test",
    "debug": true,
    "uid": 0,
    "mount_dir": "./mount_dir",
    "command": "/bin/bash",
    "mounts": [
        [
            "/lib",
            "/lib"
        ],
        [
            "/lib64",
            "/lib64"
        ]
    ],
    "clone": [
        "CLONE_NEWNS",
        "CLONE_NEWCGROUP",
        "CLONE_NEWPID",
        "CLONE_NEWIPC",
        "CLONE_NEWNET",
        "CLONE_NEWUTS"
    ],
    "cgroups-v1": {
        "cpu.shares": "256",
        "pids.max": "64",
        "blkio.bfq.weight": "64",
        "memory.limit_in_bytes": "1073741824"
    }
}

• mount_dir is the root directory where the container runs
• mounts is the external directory that the container needs to mount
• command is the path and arguments to the application running inside the container
• clone is the process running command CLONE_FLAG, see man clone
• cgroups-v1 is used to limit the resources of the container, see Control Groups Version 1

Dependencies

• plog (MIT): Portable, simple and extensible C++ logging library
• result (MIT): Result<T, E> for Modern C++
• cmd_line_parser (MIT): Command line parser for C++17.
• libseccomp (LGPL-2.1): The main libseccomp repository
• nlohmann_json (MIT): JSON for Modern C++

REFERENCES

• Linux containers in 500 lines of code
• Book: The Linux Programming Interface
• The Linux Kernel documentation¶
• OS-level virtualization wikipeidia
• LXC is a userspace interface for the Linux kernel containment features
• Advanced Bash-Scripting Guide - Appendix E. Exit Codes With Special Meanings
• Inter-process communication in Linux: Sockets and signals
• Wikipedia: Linux namespaces
• CAP_SYS_ADMIN: the new root
• Mount namespaces and shared subtrees
• Mount namespaces, mount propagation, and unbindable mounts
• Linux user namespaces might not be secure enough?
• Linux File Permission: uid vs gid
• Difference between Real User ID, Effective User ID and Saved User ID
• Introduction to Trusted Execution Environment: ARM's TrustZone
• eMMC transfer state.jssm
• List of Linux Syscalls
• Linux kernel modules drivers
• seccomp wikipeidia
• seccomp docker doc
• Control groups series
• New Linux Kernel cgroups Vulnerability Could Let Attackers Escape Container
• How to manage cgroups with CPUShares
• Limits on resources in Linux

LICENSE

Copyright (C) 2023 Muqiu Han [email protected]

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

bonding's Issues

Unable to umount automatically generated hostname

Cannot write cgroups settings: Permission denied